rffdb 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bc32e7e6da39ca78200a564f07ababf89cb3749f
-  data.tar.gz: a9978b86ec538b44b238e10e32fa85bb4bc83136
+  metadata.gz: 1663bc00dcb1ccd67c4e62f73367682709c603b3
+  data.tar.gz: ba8637b384bb8215977d852b5e1f0e483fd0f638
 SHA512:
-  metadata.gz: 8220e8ef033aa49a605148edf591334d6449e569ca38a3a823b2b6019759d077e390a3be3e1d6e5c718b22e79eeecf9a3c0b42443fb057c16748f40978b2fd22
-  data.tar.gz: 84ccd13638927c947da052720ffda3fcd50869a0a267308f5c9a6e466deebbb8a908929b31bba261a839f60b1bdd9048878f981b7d19e360dc0cd888b7409dfb
+  metadata.gz: 013ed8f87707dc0e6f71909951e646e20fc682d5851c60a447bff9975bd5e8620a7bc0b86a8d6a70b28150dd5a06935c26d119e3891af4959413cd370b12cccd
+  data.tar.gz: 98985078b1ed11cf51a28d11f1355b5ac056f8c82336f8af7229a935fd726cbe188c4d96b0ee6582b446b7ad419fcb033cda43c7fd03300f9d312c10025359b6

data/README.markdown

@@ -0,0 +1,167 @@
+Ruby Flat File DB
+=================
+
+About
+-----
+This is a really horrible idea for anything requiring high performance, but it is a pretty good way to demonstrate how to create a gem and simple framework in Ruby. This is meant to emulate ActiveRecord or DataMapper, without all the performance, scalabilty, and thread-safety concerns, and meant to be used with really poor database storage formats, like YAML or JSON. **Pay attention to this:** This is a demonstration of Ruby and frameworks, and not to be used in any kind of production environment.
+
+The gem is currently built around the concepts of "documents" and "storage engines". The rffdb gem is built to allow defining and choosing "storage engines" per database model. Database models are subclasses of the `Document` class, and storage engines are subclasses of the `StorageEngine` class.
+
+Some interesting concepts have been introduced (mostly to experiment), such as lazy-loading of model data, a caching layer between model instances and their persistent storage (a simple LRU Cache per model as an instance of `RubyFFDB::CacheProviders::LRUCache`, of course), with more to come. I plan on eventually adding thread-safety through the use of more singletons, with a semaphore or mutex around the persistent storage (with a non-blocking storage pool as an eventual option), indexes and other metadata, full-text search, and maybe someday an embedded web service for serving up the FFDB.
+
+Building
+-----
+
+While it is recommended to simply install via a normal rubygems search via ` gem install rffdb` (or adding `gem "rffdb"` to your Gemfile), you can build and install the gem yourself. This can be done like so:
+
+    #!bash
+    # need Mercurial to clone the repo... or download it from https://bitbucket.org/jgnagy/rffdb/get/tip.zip
+    hg clone https://bitbucket.org/jgnagy/rffdb
+    cd rffdb
+    # highly recommend using RVM here, and Ruby 2.x or above
+    gem build rffdb.gemspec
+    # install what you just built
+    gem install ./rffdb-*.gem
+
+Sometimes you might get lucky and there's a semi-recent version of the pre-built gem available on bitbucket [here](https://bitbucket.org/jgnagy/rffdb/downloads).
+
+Usage
+-----
+
+Require the right gem(s):
+
+    #!ruby
+    require 'rffdb'
+  
+The `YamlEngine` storage engine is included by default. To include additional storage engines (like the JSON engine), just require them:
+
+    #!ruby
+    require 'rffdb/storage_engines/json_engine'
+
+Now you must define a document model. Let's call this model "Product", like we're making an app to sell things:
+
+    #!ruby
+    class Product < RubyFFDB::Document
+    end
+
+Now that's a pretty lame document, because all it has is an "id" attribute:
+
+    #!ruby
+    product = Product.new
+    product.id            # => 1
+
+Let's start over, and this time make it better:
+
+    #!ruby
+    class Product < RubyFFDB::Document
+      attribute :name,        :class => String
+      attribute :price,       :class => Float
+      attribute :style,       :class => String
+      attribute :description, :class => String
+    end
+
+Now our Product class can do more interesting things, like store data. Yay! Here's how we use it:
+
+    #!ruby
+    product = Product.new
+    product.name  = "Awesome Sauce 5000"
+    product.price = 19.95
+    product.style = "saucy"
+    product.description = "A sauce above the rest. Easily 10x more awesome than any other sauce."
+    product.commit    # or product.save
+
+Now to pull it up later:
+
+    #!ruby
+    product = Product.get(1)
+    product.price     # => 19.95
+
+If you suspect someone else has written to the file, or that it has otherwise changed since you last loaded it, just refresh it:
+
+    #!ruby
+    product.refresh
+
+If you want to make another model that uses a different storage engine, just specify the class when you define the model:
+
+    #!ruby
+    class Customer < RubyFFDB::Document
+      engine RubyFFDB::StorageEngines::JsonEngine  # default is RubyFFDB::StorageEngines::YamlEngine
+      
+      attribute :address,       :class => String
+      attribute :first_name,    :class => String
+      attribute :last_name,     :class => String
+      attribute :phone_number,  :class => String
+      attribute :email,         :class => String, :format => /[a-zA-Z0-9_.+-]{2,}[a-zA-Z0-9]@([a-zA-Z0-9_.+-]{2,}[a-zA-Z0-9])+/
+    end
+    
+    customer = Customer.new
+    customer.email = "abcd"
+    #  RubyFFDB::Exceptions::InvalidInput raised
+
+Whoa, see what just happened? We used a different storage engine, and we validated the format of email addresses! That's right, attributes support specifying a format for Strings using a regular expression. You can also have it execute arbitrary validations (defined in the model class) as long as they're methods that accept a single input: the value you're attempting to set the attribute to:
+
+    #!ruby
+    class Payment < RubyFFDB::Document
+      # The "engine" DSL method also provides a means to customize caching
+      engine RubyFFDB::StorageEngines::JsonEngine,
+        :cache_provider => RubyFFDB::CacheProviders::RRCache,
+        :cache_size     => 200
+      attribute :cc_vendor,  :class => String, :validate => :valid_payment_methods
+      attribute :amount,     :class => Float
+      
+      def valid_payment_methods(payment_method)
+        ['visa', 'master card'].include? payment_method
+      end
+    end
+    
+    payment = Payment.new
+    payment.amount = 22.17
+    payment.cc_vendor = "amex"
+    #  RubyFFDB::Exceptions::FailedValidation raised
+
+Instances of `Document` (or its collection class, `DocumentCollection`) support querying via attributes:
+
+    #!ruby
+    # All payments... ever
+    payments = Payments.all
+    
+    # Just payments made with Visa
+    visa_payments = Payments.where(:cc_vendor, 'visa')
+    
+    # Just visa payments of more than $100
+    #   Notice we can just query an existing collection
+    #   Also note the clunky syntax. You specify "attribute", then "value", then the comparison method.
+    #   Valid comparison methods include: '>', '>=', '<', '<=', '==', or the special 'match' method.
+    big_visa_payments = visa_payments.where(:amount, 100.00, '>')
+    
+    # Just master card payments of less than $10
+    #   Notice that AND queries are just chaining WHERE queries
+    little_mc_payments = Payments.where(:amount, 10.00, '<').where(:cc_vendor, 'master card')
+
+The possibilities are endless, but this is it for now.
+
+License
+-------
+
+RubyFFDB is distributed under the MIT License
+
+To Do
+-----
+
+* YARD documentation on everything
+* Thread-safety
+* Thread-pool for non-blocking / asynchronous writing to disk (must be optional and default to disabled)
+* Indexing of columns, defined at model
+* Full-text searchable fields, configured on model
+* Write a method for clearing cache (globally and at the Model level) and invalidating individual instances (at the instance level)
+* Add a way of disabling lazy-loading of data from disk at the model level
+* Add "order_by" and a method for pagination of results (like LIMIT)
+* Additional cache providers (at least SLRU and LFU)
+* More Storage Engines (perhaps XML)
+
+Contributing
+------------
+
+Honestly, the point of this framework is for my own personal growth and learning. I'm trying hard to build the features I want into the framework without relying on the guts of other tools. I clearly rip off the methods exposed by other tools (meaning I'm designing a framework that you can interact with in a familiar way), but I'm trying to do it without knowing _how_ others did it.
+
+That said, I welcome pull-requests. I may or may not use your code, but I encourage the growth of others too. If this project inspires you to contribute, feel free to fork my code and submit a pull request. If you're okay with the MIT license and you're open to me shamelessly claiming your code as my own (it'd have to be a pretty amazing contribution for your name to show up anywhere but the commit history), go for it.

data/lib/rffdb/constants.rb

@@ -0,0 +1,4 @@
+module RubyFFDB
+  # Data directory for DB storage
+  DB_DATA = ENV["RFFDB_DB_DATA"] ? File.expand_path(ENV["RFFDB_DB_DATA"]) : File.expand_path(File.join("~", ".rffdb", "data"))
+end

data/lib/rffdb/storage_engines/json_engine.rb

@@ -45,7 +45,7 @@ module RubyFFDB
       end
 
       def self.file_path(type, object_id)
-        File.join(type.to_s.gsub('::', "__"), 'documents', object_id.to_s + ".json")
+        File.join(DB_DATA, type.to_s.gsub('::', "__"), 'documents', object_id.to_s + ".json")
       end
     end
   end

data/lib/rffdb/storage_engines/yaml_engine.rb

@@ -43,7 +43,7 @@ module RubyFFDB
       end
 
       def self.file_path(type, object_id)
-        File.join(type.to_s.gsub('::', "__"), 'documents', object_id.to_s + ".yml")
+        File.join(DB_DATA, type.to_s.gsub('::', "__"), 'documents', object_id.to_s + ".yml")
       end
     end
   end

data/lib/rffdb/version.rb

@@ -1,3 +1,3 @@
 module RubyFFDB
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

data/lib/rffdb.rb

@@ -1,5 +1,6 @@
 require 'ostruct'
 require 'rffdb/version'
+require 'rffdb/constants'
 require 'rffdb/exception'
 require 'rffdb/exceptions/cache_exceptions'
 require 'rffdb/exceptions/document_exceptions'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rffdb
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Jonathan Gnagy
@@ -17,10 +17,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- README.markdown
 - lib/rffdb.rb
 - lib/rffdb/cache_provider.rb
 - lib/rffdb/cache_providers/lru_cache.rb
 - lib/rffdb/cache_providers/rr_cache.rb
+- lib/rffdb/constants.rb
 - lib/rffdb/document.rb
 - lib/rffdb/document_collection.rb
 - lib/rffdb/exception.rb