Commit 653b969e authored by Robert Speicher's avatar Robert Speicher

Merge branch 'docs-gitlab-utilities' into 'master'

Add documents for GitLab utilities

See merge request gitlab-org/gitlab-ce!16161
parents f4c4bc97 a265ac25
......@@ -27,6 +27,7 @@ comments: false
## Backend guides
- [GitLab utilities](utilities.md)
- [API styleguide](api_styleguide.md) Use this styleguide if you are
contributing to the API.
- [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers
......
# GitLab utilities
We developed a number of utilities to ease development.
## [`MergeHash`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/merge_hash.rb)
* Deep merges an array of hashes:
``` ruby
Gitlab::Utils::MergeHash.merge(
[{ hello: ["world"] },
{ hello: "Everyone" },
{ hello: { greetings: ['Bonjour', 'Hello', 'Hallo', 'Dzien dobry'] } },
"Goodbye", "Hallo"]
)
```
Gives:
``` ruby
[
{
hello:
[
"world",
"Everyone",
{ greetings: ['Bonjour', 'Hello', 'Hallo', 'Dzien dobry'] }
]
},
"Goodbye"
]
```
* Extracts all keys and values from a hash into an array:
``` ruby
Gitlab::Utils::MergeHash.crush(
{ hello: "world", this: { crushes: ["an entire", "hash"] } }
)
```
Gives:
``` ruby
[:hello, "world", :this, :crushes, "an entire", "hash"]
```
## [`StrongMemoize`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/strong_memoize.rb)
* Memoize the value even if it is `nil` or `false`.
We often do `@value ||= compute`, however this doesn't work well if
`compute` might eventually give `nil` and we don't want to compute again.
Instead we could use `defined?` to check if the value is set or not.
However it's tedious to write such pattern, and `StrongMemoize` would
help us use such pattern.
Instead of writing patterns like this:
``` ruby
class Find
def result
return @result if defined?(@result)
@result = search
end
end
```
We could write it like:
``` ruby
class Find
include Gitlab::Utils::StrongMemoize
def result
strong_memoize(:result) do
search
end
end
end
```
* Clear memoization
``` ruby
class Find
include Gitlab::Utils::StrongMemoize
end
Find.new.clear_memoization(:result)
```
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment