staticmodel 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 89e840ef250a7502da3f788a2c211db15cd2d914
-  data.tar.gz: a06c94ca8374d4ef8cd5b08aeba68f0b8e429a11
+  metadata.gz: dfc783f3c6a3bcef6e22dfb42a356936822dc3b6
+  data.tar.gz: d327a1ea6096c87b22ffab01133ff1988019d761
 SHA512:
-  metadata.gz: abd7fd8933701a9edb5c67f602311e449afc623adc7e768ca5784fa5fc63df9a8218d35836ddbd0b1f227eddd43194887d15267d133e11051d83dbaa794bfeac
-  data.tar.gz: 08e25d28cb2262d02ced4b8966ac8cd9b920bdc8fe844eca3f0fac3a6f8e3581ae68ee5f6d60b5982a930dee9a24bd122ea655b0fa3236c42455e76331f5c669
+  metadata.gz: 96bfbb74156e8db0a9163cef1b22c26c4107f7ee6d070561de6b90503e76cab5087dc8a221adcb796fbf2881c92b8bae1e3f45ebe7a5fe78f6ad5d455599ae44
+  data.tar.gz: 2f2cbf9eea84a2bb9ee77d4d4952ae6b45a65739103b20688ab8d5cd40242be138b8c8ab5fa9023fb4bf7364ef33ecf05958008fae7d5a8d645b39a137a3c69a

data/README.md

@@ -1,8 +1,6 @@
 # StaticModel
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/staticmodel`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Read-only ActiveRecord-like interface to query static YAML files. 
 
 ## Installation
 
@@ -22,20 +20,235 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+StaticModel usage is pretty similar to ActiveRecord. Although the gem was designed with Rails in mind, it can be used in any Ruby project.
+
+To start using StaticModel you need to:
+
+* Inherit from `StaticModel::Base`.
+* Define the source of your data.
+* Define your attributes and/or your default values.
+
+
+### Inherit from `StaticModel::Base`
+
+Just like with ActiveRecord, your models need to inherit from `StaticModel::Base`.
+
+```ruby
+require "staticmodel"
+
+class Country < StaticModel::Base
+end
+```
+
+#### Primary key
+
+StaticModel assumes that each model can be identified by a primary key. A model instance’s primary key is always available as `model.id` whether you name it the default `id` or set it to something else.
+
+It's possible to override the attribute that should be used as the model's primary key using the `primary_key=` method:
+
+```ruby
+class Country < ActiveRecord::Base
+  self.primary_key = "code"
+  
+  attribute :code, String
+  attribute :name, String 
+end
+
+Country.all
+# => [
+#      #<Country code="ES", name="Spain">,
+#      #<Country code="NL", name="Netherlands">
+#    ]
+
+Country.primary_key # => "code"
+country = Country.find("ES") # => #<Country code="ES", name="Spain">
+country.id # => "ES"
+contry.name # => "Spain"
+```
+
+Or you can also override the `primary_key` method yourself:
+
+```ruby
+class Country < ActiveRecord::Base
+  def self.primary_key
+    "code"
+  end
+  
+  attribute :code, String
+  attribute :name, String 
+end
+
+Country.primary_key # => "code"
+```
+
+#### Levels of inheritance
+
+StaticModel also supports several levels of inheritance:
+
+```ruby
+require "staticmodel"
+
+class Country < StaticModel::Base
+  self.primary_key = "code"
+  
+  attribute :code, String
+  attribute :name, String 
+end
+
+class MyCountry < Country
+end
+
+class MyOtherCountry < Country
+  self.primary_key = "my_other_code"
+end
+
+MyCountry.primary_key # => "code"
+MyOtherCountry.primary_key # => "my_other_code"
+```
+
+### Define the source of your data
+
+By default, StaticModel uses a naming convention to find out how the mapping between models and YAML files should be created. It will pluralize your class names to find the respective YAML file. So, for a class Book, you should have a YAML file called **books**. The StaticModel pluralization mechanisms are based on [ActiveSupport](https://github.com/rails/rails/tree/master/activesupport) which is very powerful, being capable to pluralize (and singularize) both regular and irregular words. When using class names composed of two or more words, the model class name should follow the Ruby conventions, using the CamelCase form, while the file name must contain the words separated by underscores. Examples:
+
+* YAML file - Plural with underscores separating words (e.g., book_clubs).
+* Model Class - Singular with the first letter of each word capitalized (e.g., BookClub).
+
+It's very common to organize all your YAML files into a single directory. To tell StaticModel where it can find your static files you can specify the load path anywhere in your code with:
+
+```ruby
+StaticModel.configure do |config|
+  config.base_data_path = File.join(Rails.root, "config/data")
+end
+``` 
+
+If your YAML files are not located in the same directory or you don't want to follow the naming conventions, you can define per model the specific YAML file's path with the `data_path=` method:
+
+```ruby
+class Country < StaticModel::Base
+  self.data_path = File.join(Rails.root, "config/data/countries.yml")
+end
+```
+
+#### YAML format
+
+The format of the YAML file is very simple, an array of hashes. This could be an example for a `countries.yml` file:
+
+```yaml
+---
+- code: ES
+  name: Spain
+  population: 46770000
+- code: NL
+  name: Netherlands
+  population: 16800000
+```
+
+### Define your attributes and/or your default values
+
+StaticModel depends on the well-written [Virtus](https://github.com/solnic/virtus) gem to define its attributes. Here is a basic example of the flexibility that it provides:
+
+
+```ruby
+class Country < StaticModel::Base
+  attribute :id, String
+  attribute :name, String
+  attribute :population, Integer, default: 0
+  attribute :european, Boolean, default: false
+  attribute :province_names, Array[String]
+end
+
+country = Country.all.first
+country.id             # => "ES"
+country.name           # => "Spain"
+country.population     # => 46770000
+country.european       # => true
+country.province_names # => ["Madrid", "Barcelona", ...]
+```
+
+Advanced usage of the StaticModel attributes can be found at the [Virtus documentation](https://github.com/solnic/virtus).
+
+
+## Query interface
+
+### all
+
+Returns all the records.
+
+```ruby
+Country.all
+# => [
+#      #<Country id="ES", name="Spain" european=true>,
+#      #<Country id="NL", name="Netherlands" european=true>,
+#      #<Country id="CO", name="Colombia" european=true>
+#    ]
+```
+
+### where(_criteria_)
+
+The `where` method allows you to specify conditions to limit the records returned, like the `WHERE`-part of the SQL statement. Conditions must be specified as a hash.
+
+```ruby
+Country.where(european: true)
+# => [
+#      #<Country id="ES", name="Spain" european=true>,
+#      #<Country id="NL", name="Netherlands" european=true>
+#    ]
+```
+
+### find(_id_)
+
+Using the `find` method, you can retrieve the object corresponding to the specified primary key that matches the supplied `id`.
+
+```ruby
+Country.find("ES") # => #<Country id="ES", name="Spain">
+Country.find("KO") # => StaticModel::NotFound
+```
+
+The `find` method will raise a `StaticModel::NotFound` exception if no matching record is found.
+
+### find\_by(_criteria_)
+
+The `find_by` method finds the first record matching some conditions.
+
+```ruby
+Country.find_by(name: "Spain") # => #<Country id="ES", name="Spain">
+Country.find_by(name: "Invalid") # => nil
+```
+
+### find\_by!(_criteria_)
+
+The `find_by!` method behaves exactly like `find_by`, except that it will raise `StaticModel::NotFound` if no matching record is found.
+
+```ruby
+Country.find_by!(name: "Spain") # => #<Country id="ES", name="Spain">
+Country.find_by!(name: "Invalid") # => StaticModel::NotFound
+```
+
+### exists?(_criteria_)
+
+If you simply want to check for the existence of the object there's a method called `exists?`. This method will use the same mechanism as `find`, but instead of returning an object it will return either `true` or `false`.
+
+```ruby
+Country.exists?(name: "Spain") # => true
+Country.exists?(name: "Invalid") # => false
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `script/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `script/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/staticmodel. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/fertapric/staticmodel. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
 
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
+## Author
+
+Fernando Tapia Rico, @fertapric
+

data/lib/static_model.rb

@@ -5,6 +5,7 @@ require "yaml"
 require "static_model/base"
 require "static_model/configuration"
 require "static_model/errors"
+require "static_model/version"
 
 module StaticModel
   autoload :Shortcut, "static_model/shortcut"

data/lib/static_model/base.rb

@@ -3,7 +3,7 @@ module StaticModel
     include Virtus.model
 
     def id
-      defined?(super) ? super : __send__(primary_key)
+      defined?(super) ? super : __send__(self.class.primary_key)
     end
 
     def self.primary_key
@@ -52,7 +52,7 @@ module StaticModel
       where(criteria).first
     end
 
-    def self.exist?(criteria = {})
+    def self.exists?(criteria = {})
       if criteria.is_a?(Hash)
         !!find_by(criteria)
       else

data/lib/static_model/version.rb

@@ -2,7 +2,7 @@ module StaticModel
   VERSION = [
     VERSION_MAJOR = 1,
     VERSION_MINOR = 0,
-    VERSION_TINY = 0,
+    VERSION_TINY = 2,
     VERSION_PRE = nil
   ].compact.join(".")
 end

data/lib/staticmodel.rb

@@ -0,0 +1 @@
+require "static_model"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: staticmodel
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Fernando Tapia Rico
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-16 00:00:00.000000000 Z
+date: 2015-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: virtus
@@ -95,6 +95,7 @@ files:
 - lib/static_model/errors.rb
 - lib/static_model/shortcut.rb
 - lib/static_model/version.rb
+- lib/staticmodel.rb
 homepage: https://github.com/fertapric/staticmodel
 licenses:
 - MIT