memstore 1.2.1 → 2.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e09df24ba555d687f405c140c6ccbacaf4b42963
+  data.tar.gz: 462f77bf9be2d36d7cd98f770c59b65149fdd5e8
+SHA512:
+  metadata.gz: 827ae9142869655c018017fe3ca335333561dc9504ab0ef46b5e0dae02b21b3b8f9c83bdad00090a6e9fc2c1ca9fc4fa289795cc1cdd5465a12680b07d037efb
+  data.tar.gz: 3c92d873c50ddbb71f8ec8a67190edc65f003a67221526ceae430ee6446fb3a3bc6a3714ee2d5b76c07448265af1862e99668eb638b8fabd3990f719d7f38ec5

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.ruby-version

data/.rdoc_options

@@ -0,0 +1,19 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+charset: UTF-8
+static_path: []
+rdoc_include:
+- .
+exclude:
+- spec
+- Gemfile
+- Gemfile.lock
+- Rakefile
+- created.rid
+main_page: README.md
+markup: tomdoc
+hyperlink_all: false
+line_numbers: false
+show_hash: false
+tab_width: 2
+visibility: :protected

data/README.md

@@ -2,265 +2,134 @@
 
 *A simple in-memory data store.*
 
-MemStore is a simple in-memory data store that supports adding, retrieving and deleting items as well as complex search queries and easy serialization.
+MemStore is a simple in-memory data store that supports complex search queries.
 
-It’s not in any way supposed to be a “real” database. However, it can replace a database in small applications or prototypes.
+It’s not in any way supposed to be a database. However, it can be used instead of database in small applications or prototypes.
 
-## Installation
+**Important: Ruby 2.1 is required.**
 
-Add this line to your application's Gemfile:
+## Basics
 
-```ruby
-gem "memstore"
-```
-
-And then execute:
-
-```sh
-$ bundle
-```
-
-Or install it yourself as:
-
-```sh
-$ gem install memstore
-```
-
-## Usage
-
-- [Basics](#basics)
-  - [Objects vs. Hashes](#objects-vs-hashes)
-  - [Adding Items](#adding-items)
-  - [Retrieving Items](#retrieving-items)
-  - [Deleting Items](#deleting-items)
-- [Search Queries](#search-queries)
-- [Serialization](#serialization)
-  - [Binary](#binary)
-  - [Hash](#hash)
-  - [YAML](#yaml)
-  - [JSON](#json)
-  - [MessagePack](#messagepack)
-  - [Concurrent Access](#concurrent-access)
-
-### Basics
-
-Creating a data store is utterly simple:
+Creating a data store is straightforward:
 
 ```ruby
 store = MemStore.new
-```
-
-By default, objects are indexed using `Object#hash`.
-
-If a different property should be used, it can be specified like this:
-
-```ruby
-store = MemStore.new(:id)
-```
-
-The property needs to be truly unique for all objects since it’s used as a hash key internally.
-
-An items collection can also be provided on creation:
-
-```ruby
-store = MemStore.new(nil, { ... }) # to use Object.hash as key
-store = MemStore.new(:id, { ... }) # to use custom key
-```
-
-The collection must be a hash that correctly maps the used key to each item.
-
-#### Objects vs. Hashes
-
-MemStore comes in two flavors: `ObjectStore` and `HashStore`.
-
-They’re basically the same, but `ObjectStore` accesses items through `item.attribute` while `HashStore` accesses items through `item[attribute]`.
-
-`ObjectStore` is the default variant:
-
-```ruby
-store = MemStore.new
-# is equal to
-store = MemStore::ObjectStore.new
-```
-
-`HashStore` needs to be created explicitly:
-
-```ruby
-store = MemStore::HashStore.new
-```
-
-If no key attribute is specified, `HashStore` will also use `Object#hash`.
-
-#### Adding Items
-
-`items` provides direct access to the internal items hash.
-
-```ruby
-store.items
-# => {}
-store.items = { 1 => a, 2 => b, 3 => c }
-# => { 1 => a, 2 => b, 3 => c }
-```
-
-`insert` adds one or multiple items and returns the data store itself:
-
-```ruby
-store.insert(a, b, c)
 # => store
 ```
 
-Since it returns the data store, items can be added right after instantiation:
+Adding items is equally simple. Add a single item using the shovel operator `<<` or multiple items using `add`:
 
 ```ruby
-store = MemStore.new.insert(a, b, c)
+store << a
 # => store
-```
-
-MemStore also supports the shovel operator `<<` for adding items.  
-Only one item can be added at a time but it’s chainable:
-
-```ruby
-store << a << b << c
+store.add(a, b, c)
 # => store
 ```
 
-#### Retrieving Items
-
-`length` (or `size`) returns the current number of items:
+To make things easier, MemStore’s constructor takes a collection of items that will be added right away:
 
 ```ruby
-store.length
-# => 3
+store = MemStore.new(items: [a, b, c])
+# => store
 ```
 
-The bracket operator `[]` is used to look up items by their key.  
-If a single key is given, a single item will be returned.  
-If multiple keys are given, an array of items will be returned with `nil` when there is no item for a key.
+You can access single items by their key (see [Customization](#customization)) using the bracket operator `[]` or multiple items using `get`:
 
 ```ruby
 store[1]
 # => a
-store[1, 2, 3]
+store.get(1, 2, 3)
 # => [a, b, c]
 ```
 
-Ranges are also supported and can even be combined with single keys:
+You can also get all items at once using `all` and a hash of all items with their keys using `items`:
 
 ```ruby
-store[1..3]
+store.all
 # => [a, b, c]
-store[1..3, 6]
-# => [a, b, c, f]
+store.items
+# => { 1 => a, 2 => b, 3 => c }
 ```
 
-#### Deleting Items
+## Queries
 
-`delete_items` (or `delete_item`) deletes items by reference and returns them.  
-This is considered the default use case and therefore also available as `delete`.
+MemStore provides methods to find, count and delete items using complex queries:
 
-If one item is given, it is deleted and returned.  
-If multiple items are given, they are deleted and returned as an array.
+- `find_*` returns all items matching the query
+- `first_*` returns the first item matching the query
+- `count_*` returns the number of items matching the query
+- `delete_*` deletes and returns all items matching the query
 
-```ruby
-store.delete_item(a)
-# => a
-store.delete_items(b, c, d)
-# => [b, c, d]
-store.delete(e, f, g)
-# => [e, f, g]
-```
-
-This is considered the default use case and therefore also available as `delete`.
-
-`delete_keys` (or `delete_key`) deletes items by key and returns them.  
-Again, one or multiple items can be deleted at a time and even ranges are accepted.
-
-```ruby
-store.delete_key(1)
-# => a
-store.delete_keys(2, 3, 4)
-# => [b, c, d]
-store.delete_keys(5..7, 9)
-# => [e, f, g, i]
-```
+These methods have one of the following suffixes:
 
-### Search Queries
+- `*_all` matches items *fulfilling all* conditions
+- `*_any` matches items *fulfilling at least one* condition
+- `*_one` matches items *fulfilling exactly one* condition
+- `*_not_all` matches items *violating at least one* condition
+- `*_none` matches items *violating all* conditions
 
-The following methods are available to query the data store:
-
-- `find_all` (alias `find`)
-- `find_any`
-- `find_one`
-- `find_not_all`
-- `find_none`
-- `first_all` (alias `first`)
-- `first_any`
-- `first_one`
-- `first_not_all`
-- `first_none`
-- `count_all` (alias `count`)
-- `count_any`
-- `count_one`
-- `count_not_all`
-- `count_none`
-
-The first part indicates what is returned:
-
-- `find_*` returns all matches.
-- `first_*` returns the first match.
-- `count_*` returns the number of matches.
+In other words:
 
-The second part indicates how conditions are evaluated:
+- `all` means `condition && condition && ...`
+- `any` means `condition || condition || ...`
+- `one` means `condition ^ condition ^ ...`
+- `not all` means `!(condition && condition && ...)` or `!condition || !condition || ...`
+- `none` means `!(condition || condition || ...)` or `!condition && !condition && ...`
 
-- `*_all` matches items *fulfilling all* conditions.
-- `*_any` matches items *fulfilling at least one* condition.
-- `*_one` matches items *fulfilling exactly one* condition.
-- `*_not_all` matches items *violating at least one* condition.
-- `*_none` matches items *violating all* conditions.
+For convenience, there are aliases for the `*_all` variants:
 
-In other words:
+- `find` is an alias of `find_all`
+- `first` is an alias of `first_all`
+- `count` is an alias of `count_all`
+- `delete` is an alias of `delete_all`
 
-- `all` means `condition && condition && ...`.
-- `any` means `condition || condition || ...`.
-- `one` means `condition ^ condition ^ ...`.
-- `not all` means `!(condition && condition && ...)` or `!condition || !condition || ...`.
-- `none` means `!(condition || condition || ...)` or `!condition && !condition && ...`.
+All methods take a hash of conditions and/or a block.
 
-All variants take a `conditions` hash and an optional block.
+The hash is expected to map attributes (see [Customization](#customization)) to conditions.  
+Conditions are evaluated using the case equality operator: `condition === item`
 
-The hash maps attributes names to conditions that should be tested.  
-Conditions are evaluated using the `===` operator and can be virtually anything:
+This means conditions can be virtually anything:
 
 ```ruby
-store.find(name: "Fred", age: 25)
-store.find(name: /red/i, age: 10..30)
+store.find(name: "John", age: 42)
+# is equivalent to item.name == "John" && item.age == 42
+store.find(name: /^Jo/, age: 23..42)
+# is equivalent to /^Jo/ =~ item.name && (23..42).include?(item.age)
 store.find(child: MyClass)
+# is equivalent to item.child.kind_of?(MyClass)
 store.find(child: -> child { child.valid? })
+# is equivalent to proc.call(item.child)
 ```
 
-Additional types can be used in conditions by supporting the `===` operator. For example:
+You can enable additional types of conditions simply by implementing `===`.  
+For example, MemStore also supports arrays using an internal refinement:
 
 ```ruby
-class Array
-	def ===(obj)
-		self.include?(obj)
-	end
-end
-
 store.find(age: [23, 25, 27])
+# is equivalent to [23, 25, 27].include?(item.age)
+```
+
+The implementation looks like this:
+
+```ruby
+refine Array do
+  def ===(obj)
+    include?(obj)
+  end
+end
 ```
 
-The block is invoked with the item *after* the conditions are evaluated. It should return a boolean value:
+The block is invoked with the item *after* the conditions are evaluated.
 
 ```ruby
 store.find(age: 25) { |item| item.age - item.child.age > 20 }
-# is evaluated as (item.age == 25) && (item.age - item.child.age > 20)
+# is equivalent to item.age == 25 && item.age - item.child.age > 20
 ```
 
-In addition to the evaluation logic, the arrays returned by all variants of `find_*` can be merged:
+In addition to the query logic, you can merge the arrays returned by `find_*`:
 
 ```ruby
-store.find(...) | store.find(...) | store.find(...)
+store.find_all(...) | store.find_any(...) | store.find_none(...)
 ```
 
 Note that the pipe operator `|` already eliminates duplicates:
@@ -270,173 +139,128 @@ Note that the pipe operator `|` already eliminates duplicates:
 # => [a, b, c, d, e]
 ```
 
-### Serialization
+## Customization
 
-MemStore support various ways of de-/serializing the data store.
+### Default Behavior
 
-- `ObjectStore` supports binary format.
-- `HashStore` supports binary format, hash, [YAML](http://yaml.org/), [JSON](http://www.json.org/) and [MessagePack](http://msgpack.org/).
-
-**Important:** When file IO or deserialization fails, all variants of `from_*` return `nil`.
-
-The following style ensures that there will be a (correctly configured) data store:
+By default, MemStore indexes items using `Object#hash`:
 
 ```ruby
-store = MemStore.from_file(file) || MemStore::HashStore(key, items)
+store = MemStore.new
+store << item
+# calls item.hash to retrieve key
+store[item.hash]
+# => item
 ```
 
-#### Binary
-
-Both `ObjectStore` and `HashStore` can easily be serialized to and from binary format:
+When you use `find_*`, `first_*`, `count_*` or `delete_*`, MemStore calls attributes as methods on your items using `Object#send`:
 
 ```ruby
-store.to_binary
-# => binary string
-store.to_file(file)
-# => number of bytes written
-MemStore.from_binary(binary)
-# => instance of ObjectStore or HashStore or nil
-MemStore.from_file(file)
-# => instance of ObjectStore or HashStore or nil
+store = MemStore.new
+store << item
+store.find(age: 42, name: "John")
+# calls item.age and item.name to retrieve attributes
 ```
 
-#### Hash
-
-`HashStore` can be converted to and from a hash:
+This means that it doesn’t make a difference whether you use strings or symbols in the conditions hash:
 
 ```ruby
-store.to_hash
-# => { key: ..., items: { ... } }
-MemStore::HashStore.from_hash(hash)
-# => instance of HashStore or nil
+store.find("age" => 42, "name" => "John")
+# calls item.age and item.name to retrieve attributes
 ```
 
-#### YAML
+*Note that using Strings will result in a performance penalty because `Object#send` expects Symbols.*
+
+### Custom Key
 
-`memstore/yaml` enables serialization of `HashStore` to and from [YAML](http://yaml.org/):
+You’ll probably want MemStore to use a specific attribute to index items.  
+This is possible using the `key` parameter when creating a data store:
 
 ```ruby
-require "memstore/yaml" # requires "yaml"
-
-store.to_yaml
-# => YAML string
-store.to_yaml_file(file)
-# => number of bytes written
-MemStore::HashStore.from_yaml(yaml)
-# => instance of HashStore or nil
-MemStore::HashStore.from_yaml_file(file)
-# => instance of HashStore or nil
+store = MemStore.new(key: :id)
+store << item
+# calls item.id to retrieve key
+store[item.id]
+# => item
 ```
 
-De/serialization is seamless since YAML can handle symbols and non-string keys (i.e. Psych converts them correctly).
+Whatever you provide as `key` will be treated as an attribute.  
+So, by default, the according method will be called on your item.
 
-#### JSON
+### Custom Access Method
 
-`memstore/json` enables serialization of `HashStore` to and from [JSON](http://www.json.org/):
+If you want to change how attributes are accessed, you can use the `access` parameter when creating a data store:
 
 ```ruby
-require "memstore/json" # requires "json"
-
-store.to_json
-# => JSON string
-store.to_json_file(file)
-# => number of bytes written
-MemStore::HashStore.from_json(json)
-# => instance of HashStore or nil
-MemStore::HashStore.from_json_file(file)
-# => instance of HashStore or nil
+store = MemStore.new(key: :id, access: :[])
+# now you can store hashes, e.g. { id: 5, age: 42, name: "John" }
+store << item
+# calls item[:id] to retrieve key
+store.find(age: 42, name: "John")
+# calls item[:age] and item[:name] to retrieve attributes
 ```
 
-**Important:** Symbols will be converted to strings and JSON only allows string keys.
+If you provide a Symbol or String, it will be treated as a method name.  
+*Note that providing a String will result in a performance penalty because `Object#send` expects Symbols.*
 
-```ruby
-store = MemStore::HashStore.new(:id)
-store << { id: 1 }
-store.to_hash
-# => { :key => :id, :items => { 1 => { :id => 1 } } }
-store = MemStore::HashStore.from_json(store.to_json)
-store.to_hash
-# => { :key => "id", :items => { "1" => { "id" => 1 } } }
-```
-
-The following style ensures consistent access before and after serialization:
+To access an attribute, MemStore will call the according method on your item and pass the requested attribute to it.  
+This means `key` and attributes in the conditions hash must be whatever your method expects:
 
 ```ruby
-store = MemStore::HashStore.new("id")
-store << { "id" => "1" }
-store["1"]
-# => { "id" => "1" }
+# assuming that items have a method `get` that expects a String:
+store = MemStore.new(key: "id", access: :get)
+store << item
+# calls item.get("id") to retrieve key
+store.find("age" => 42, "name" => "John")
+# calls item.get("age") and item.get("name") to retrieve attributes
 ```
 
-#### MessagePack
+### Advanced Customization
 
-`memstore/msgpack` enables serialization of `HashStore` to and from [MessagePack](http://msgpack.org/):
+If you want to do something special to obtain a key, you can provide a Proc or Method.  
+It will be passed the item for which MemStore needs a key and is expected to return a truly unique identifier for that item:
 
 ```ruby
-require "memstore/msgpack" # requires "msgpack"
-
-store.to_msgpack
-# => MessagePack binary format
-store.to_msgpack_file(file)
-# => number of bytes written
-MemStore::HashStore.from_msgpack(msgpack)
-# => instance of HashStore or nil
-MemStore::HashStore.from_msgpack_file(file)
-# => instance of HashStore or nil
-```
-
-**Important:** Symbols will be converted to strings but non-string keys are allowed.
+def special_hash(item)
+ # ...
+end
 
-```ruby
-store = MemStore::HashStore.new(:id)
-store << { id: 1 }
-store.to_hash
-# => { :key => :id, :items => { 1 => { :id => 1 } } }
-store = MemStore::HashStore.from_msgpack(store.to_msgpack)
-store.to_hash
-# => { :key => "id", :items => { 1 => { "id" => 1 } } }
+# lambda:
+store = MemStore.new(key: -> item { special_hash(item) })
+# Proc:
+store = MemStore.new(key: Proc.new { |item| special_hash(item) })
+# Method:
+store = MemStore.new(key: method(:special_hash))
 ```
 
-The following style ensures consistent access before and after serialization:
+Note that this is also a way to circumvent the access method for attributes.  
+For example, you might want to use one method `get` to access all attributes but a different method `id` should be used for indexing:
 
 ```ruby
-store = MemStore::HashStore.new("id")
-store << { "id" => 1 }
-store[1]
-# => { "id" => 1 }
+# this way, item.get(:id) would be used:
+store = MemStore.new(access: :get, key: :id)
+# circumvent the access method like this:
+store = MemStore.new(access: :get, key: -> item { item.id })
+# or even shorter:
+store = MemStore.new(access: :get, key: Proc.new(&:id))
+store << item
+# calls item.id to retrieve key
+store.find(age: 42, name: "John")
+# calls item.get(:age) and item.get(:name) to retrieve attributes
 ```
 
-#### Concurrent Access
-
-To support concurrent access, e.g. when multiple threads or processes read and write the same data store file, there’s a `with_file` equivalent of `from_file` and `to_file`.
-
-`with_file` takes a file (name) and a block. It then obtains an exclusive lock on that file, restores a data store from it or creates a new one, invokes the block with the data store and finally saves the data store back to the file. Optionally, key and/or items can be specified for when the data store is created instead of restored.
+Likewise, you can provide a Proc or Method to be called when accessing attributes.  
+It will be passed both the item in question and the attribute to be retrieved and is expected to return the appropriate value:
 
 ```ruby
-MemStore.with_file(file, key, items) do |store|
-  # create, read, update, delete
+def special_accessor(item, attribute)
+  # ...
 end
-```
-
-`MemStore.with_file` is a shortcut to `MemStore::ObjectStore.with_file`.
 
-`HashStore` offers a locking version of all its serialization methods:
-
-- `with_file` by default,
-- `with_yaml_file` when `memstore/yaml` is included,
-- `with_json_file` when `memstore/json` is included,
-- `with_msgpack_file` when `memstore/msgpack` is included.
-
-## Contributing
-
-1. Fork it on [GitHub](https://github.com/sklppr/memstore).
-2. Create a feature branch containing your changes:
-
-    ```sh
-    $ git checkout -b feature/my-new-feature
-    # code, code, code
-    $ git commit -am "Add some feature"
-    $ git push origin feature/my-new-feature
-    ```
-
-3. Create a Pull Request on [GitHub](https://github.com/sklppr/memstore).
+# lambda:
+store = MemStore.new(access: -> item, attribute { special_accessor(item, attribute) })
+# Proc:
+store = MemStore.new(access: Proc.new { |item| special_accessor(item, attribute) })
+# Method:
+store = MemStore.new(access: method(:special_accessor))
+```