sander6-daijobu 0.2.0 → 0.2.1

data/README.rdoc

@@ -1,6 +1,65 @@
 = Daijobu
 
-A library for easing serialization and deserialzation of data stuffed into Tokyo Cabinet, including flexible and fallback schemes. This will all make more sense once the documentation is written for real.
+=== "Oh no! Another key-value-store wrapper!"
+
+Don't worry, Daijobu isn't about that. Rather, it wraps the serialization/deserialzation layer of accessing key-value stores, specifically Tokyo Cabinet, but I guess with some work it could work with other things.
+
+=== "So how's it work?"
+
+Make a new, inappropriately-named Daijobu::Client object and give it your store (supported stores are MemCache, Rufus::Tokyo::Cabinet, and Rufus::Tokyo::Tyrant), and then the scheme or schemes you want to use for serialization.
+
+    rufus   = Rufus::Tokyo::Cabinet.new('casket.tch')
+    daijobu = Daijobu::Client.new(rufus, :schemes => :json)
+
+You can now use the regular hash getter and setter methods ([] and []=) without worrying about serialization.
+
+The supported schemes are :marshal (using Marshal), :json (using JSON from the json gem), :yaml (using YAML), :eval (using Kernel::eval), and :raw (using nothing).
+
+Because some schemes are very strict, and sometimes what gets dumped can't be parsed back (for example, unparsing an integer using JSON), you can specify a set of schemes. If one doesn't work, it'll try the next in the list until it succeeds in parsing.
+
+    Daijobu::Client.new(rufus, :schemes => [:json, :yaml, :eval])
+
+Daijobu doesn't do any real format-checking; if, say, Marshal.load throws an error, for whatever reason, it'll just rescue and move on to the next scheme. The success of this gem all hinges on the fact that the supported serialization formats don't have much to do with one another (except for JSON and YAML, of course), and you shouldn't ever end up parsing Ruby code as JSON accidentally, or at least not in unintended ways.
+
+You can set different read and write schemes, too. This would be useful, say, if you wanted to change the serialization format.
+
+    Daijobu::Client.new(rufus, :read => :json, :write => :raw)
+
+One last cool thing that I threw in just because: the key names in a key-value store are often namespaced. You can call these namespaces as methods on a Client object to automatically prepend that namespace to any keys asked for.
+
+    daijobu = Daijobu::Client.new(rufus, :read => :json, :write => :raw)
+    daijobu.namespace['123'] # => looks for 'namespace:123'
+    daijobu.name.space['123'] # => looks for 'name:space:123'
+
+You can set the separator (defaults to ':' because that's what I was using) on the Daijobu::NamespaceProxy class.
+
+    Daijobu::NamespaceProxy.default_separator = '/'
+    daijobu.name.space['123'] # => looks for 'name/space/123'
+
+And a last bit of syntatical sugar: you can leave off the brackets when asking for namespaced keys.
+
+    daijobu.namespace '123' # => looks for 'namespace:123'
+    daijobu.name.space '123' # => looks for 'name:space:123'
+
+=== "Anything else I should know?"
+
+Pretty much only the getting and setting APIs are implemented for the supported adapters, so fancier stuff like iterating over keys isn't there yet.
+
+Multi-get is also kind of janky right now for MemCache, due to a flaw in the memcache-client gem that assumes Marshal.load'ing on get_multi. Keys are therefore fetched one at a time.
+
+=== "What does the future hold for Daijobu?"
+
+I plan to eventually switch out my home-rolled adapters for a more complete and more-intelligently-written backend, like Moneta, but last time I checked it was broken and I needed this gem to do work right now.
+
+Until then, I'm thinking of putting in support for user-defined adapters as a stopgap, basically any object that responds to #get(key) and #set(key, value).
+
+Less of a priority is support for user-defined serialization schemes that respond to #parse(string) and #unparse(object).
+
+I also plan to take a look at ActiveRecord::Base#serialize to see if I can do something with that, because reading and writing YAML is like dying every day.
+
+=== "What's with the name?"
+
+It's my understanding that "daijobu" is Japanese for "I'm fine" or "It's okay". The hardest thing about making gems is deciding what to call them, and that's the first thing that popped into my head.
 
 == Copyright
 

data/lib/daijobu/adapter.rb

@@ -1,6 +1,16 @@
 module Daijobu
+  
+  # Daijobu::Adapter is the parent module of the various adapter classes.
   module Adapter
     
+    # Given an object, returns a new instance of the corresponding adapter based on the
+    # object's class.
+    #
+    #   MemCache              => Daijobu::Adapter::MemCacheAdapter
+    #   Rufus::Tokyo::Cabinet => Daijobu::Adapter::TokyoCabinetAdapter
+    #   Rufus::Tokyo::Tyrant  => Daijobu::Adapter::TokyoTyrantAdapter
+    #
+    # Raises Daijobu::InvalidAdapter if given a object it doesn't know about.
     def self.get(casket)
       if defined?(MemCache) && casket.is_a?(MemCache)
         Daijobu::Adapter::MemCacheAdapter.new(casket)

data/lib/daijobu/adapters/mem_cache.rb

@@ -2,12 +2,17 @@ module Daijobu
   
   module Adapter
     
+    # Daijobu::Adapter::MemCacheAdapter wraps getting and setting to a MemCache store.
+    # Note that you can use MemCache to talk to a Tokyo Tyrant server, since they
+    # speak the same language.
     class MemCacheAdapter
       
+      # Daijobu::Adapter::MemCacheAdapter.new takes a MemCache object.
       def initialize(store)
         @store = store
       end
       
+      # Gets the key or keys given. Multiple values will be returned in a hash.
       def get(*keys)
         if keys.size == 0
           nil
@@ -18,12 +23,14 @@ module Daijobu
         end
       end
       
+      # Sets the key to the given value (using MemCache#add).
       def set(key, value)
         @store.add(key, value, 0, true)
       end
       
       private
       
+      # Gets a single key. Used internally.
       def get_one(key)
         @store.get(key, true)
       end

data/lib/daijobu/adapters/tokyo_cabinet.rb

@@ -2,12 +2,16 @@ module Daijobu
   
   module Adapter
     
+    # Daijobu::Adapter::TokyoCabinetAdapter wraps getting and setting to a Rufus::Tokyo::Cabinet store.
     class TokyoCabinetAdapter
       
+      # Daijobu::Adapter::TokyoCabinetAdapter.new takes a Rufus::Tokyo::Cabinet object.
       def initialize(store)
         @store = store
       end
       
+      # Gets the key or keys given, using Cabinet#[] or Cabinet#lget.
+      # Multiple values should be returned in a hash, but that's really up to the Cabinet object.
       def get(*keys)
         if keys.size == 0
           nil
@@ -18,6 +22,7 @@ module Daijobu
         end
       end
       
+      # Sets the key to the given value (using Cabinet#[]=).
       def set(key, value)
         @store[key] = value
       end

data/lib/daijobu/adapters/tokyo_tyrant.rb

@@ -2,12 +2,16 @@ module Daijobu
   
   module Adapter
     
+    # Daijobu::Adapter::TokyoTyrantAdapter wraps getting and setting to a Rufus::Tokyo::Tyrant store.
     class TokyoTyrantAdapter
       
+      # Daijobu::Adapter::TokyoTyrantAdapter.new takes a Rufus::Tokyo::Tyrant object.
       def initialize(store)
         @store = store
       end
       
+      # Gets the key or keys given, using Tyrant#[] or Tyrant#lget.
+      # Multiple values should be returned in a hash, but that's really up to Tyrant object.
       def get(*keys)
         if keys.size == 0
           nil
@@ -18,6 +22,7 @@ module Daijobu
         end
       end
       
+      # Sets the key to the given value (using Tyrant#[]=).
       def set(key, value)
         @store[key] = value
       end

data/lib/daijobu/client.rb

@@ -1,30 +1,57 @@
 module Daijobu
+  
+  # The unfortunately-named Daijobu::Client is the serialization wrapper for key-value stores.
   class Client
 
+    # Client.new takes a key-value store as its first argument, and then a hash of serialization schemes.
+    #
+    # Options:
+    #   :schemes  => the scheme or schemes used to read and write, in order
+    #   :read     => the scheme or schemes used to read, in order. Trumped by :schemes
+    #   :write    => the scheme or schemes used to write, in order. Trumped by :schemes
     def initialize(casket, options = {})
       @adapter        = Daijobu::Adapter.get(casket)
       @read_schemes   = Daijobu::SchemeSet.new(options[:schemes] || options[:read])
       @write_schemes  = Daijobu::SchemeSet.new(options[:schemes] || options[:write])
     end
 
+    # Getter for keys. The actual getting method is handled by the specific Adapter object.
+    # You can ask for multiple keys at once, in which case this returns a hash of key => value.
     def [](*keys)
       __parse__(@adapter.get(*keys.collect { |key| key.to_s }))
     end
 
+    # Setter for keys. The actual setting method is handled by the specific Adapter object.
     def []=(key, value)
       @adapter.set(key.to_s, __unparse__(value))
     end
 
+    # Any missing method is assumed to be a namespace for keys to get. The NamespaceProxy object
+    # returned also implements the same kind of method_missing, so namespaces can be chained together.
+    #
+    #     client.namespace['key']           # => gets key 'namespace:key'
+    #     client.name.space['key']          # => gets key 'name:space:key'
+    #     client.namespace['key'] = 'value' # => sets key 'namespace:key'
+    #
+    # As an added bit of syntactic sugar, you can leave the brackets off when getting keys this way.
+    #
+    #     client.namespace 'key' # => same as client.namespace['key']
+    #
+    # See NamespaceProxy for more details about setting the separator.
     def method_missing(name, *args)
       args.empty? ? Daijobu::NamespaceProxy.new(self, name) : Daijobu::NamespaceProxy.new(self, name)[*args]
     end
 
     private
 
+    # Tries to parse (load) the string using each of the reading schemes in order.
+    # The actual parsing is done by the specific Scheme object.
     def __parse__(str)
       @read_schemes.parse(str)
     end
 
+    # Tries to unparse (dump) the object using each of the writing schemes in order.
+    # The actual unparsing is done by the specific Scheme object.
     def __unparse__(obj)
       @write_schemes.unparse(obj)
     end

data/lib/daijobu/errors.rb

@@ -1,11 +1,17 @@
 module Daijobu
   
+  # The superclass of all the errors that Daijobu raises.
   class Error < StandardError; end
 
+  # Raised when asking for a scheme that doesn't exist.
+  # Supported schemes are :marshal, :json, :yaml, :eval, and :raw.
   class UnknownScheme < Daijobu::Error; end
 
+  # Raised when the key-value-store object doesn't have a appropriate adapter.
+  # Supported stores are MemCache, Rufus::Tokyo::Cabinet, and Rufus::Tokyo::Tyrant.
   class InvalidAdapter < Daijobu::Error; end
   
+  # Raised when all of the (un)parsing schemes fail.
   class NoFallbackScheme < Daijobu::Error; end
   
 end

data/lib/daijobu/namespace_proxy.rb

@@ -2,31 +2,43 @@ module Daijobu
   class NamespaceProxy
     
     @@default_separator = ':'
+    
+    # Getter for the default separator. Default is ':'
     def self.default_separator
       @@default_separator
     end
     
+    # Setter for the default separator. I use ':', but a lot of people like '/'.
     def self.default_separator=(separator)
       @@default_separator = separator
     end
-    
+
+    # NamespaceProxy.new takes an owner (a Daijobu::Client), a namespace, and a separator (defaults 
+    # to @@default_separator).
+    # NamespaceProxy objects are typically created using Daijobu::Client#method_missing, so you're
+    # rarely going to instantiate one of these on your own.
     def initialize(owner, namespace, separator = @@default_separator)
       @owner = owner
       @namespace = namespace.to_s
       @separator = separator
     end
-    
+
+    # Sends #[] back to the owner, prepending the key given with the namespace and separator.
     def [](key)
       @owner["#{@namespace}#{@separator}#{key}"]
     end
-    
+
+    # Sends #[]= back to the owner, prepending the key given with the namespace and separator.    
     def []=(key, value)
       @owner["#{@namespace}#{@separator}#{key}"] = value
     end
-    
+
+    # Any missing method is assumed to be yet another namespace.
     def method_missing(namespace, *args)
       separator = args.shift || @@default_separator
-      Daijobu::NamespaceProxy.new(@owner, "#{@namespace}#{@separator}#{namespace}", separator)
+      @namespace = "#{@namespace}#{@separator}#{namespace}"
+      @separator = separator
+      self
     end
   end
 end

data/lib/daijobu/scheme.rb

@@ -1,6 +1,17 @@
 module Daijobu
+
+  # The Scheme module is the parent of the various serialization schemes.
   module Scheme
     
+    # Given a name, returns a new instance of the corresponding scheme.
+    #
+    #   :marshal  => Daijobu::Scheme::Marshal
+    #   :json     => Daijobu::Scheme::JSON
+    #   :yaml     => Daijobu::Scheme::YAML
+    #   :eval     => Daijobu::Scheme::Eval
+    #   :raw      => Daijobu::Scheme::Raw
+    #
+    # Raises Daijobu::UnknownScheme if given a name it can't handle. 
     def self.get(name)
       case name
       when :marshal
@@ -11,6 +22,8 @@ module Daijobu
         Daijobu::Scheme::YAML.new
       when :eval
         Daijobu::Scheme::Eval.new
+      when :raw
+        Daijobu::Scheme::Raw.new
       else
         raise Daijobu::UnknownScheme
       end

data/lib/daijobu/scheme_set.rb

@@ -1,10 +1,14 @@
 module Daijobu
+  
+  # A SchemeSet holds a bundle of schemes, and has logic for iterating over them.
   class SchemeSet
     
     DEFAULT = [ :marshal, :json, :yaml, :eval ]
     
     attr_reader :current
-    
+
+    # SchemeSet.new takes a single symbol or array of symbols and initializes a new Scheme
+    # object of the appropriate type for each one.
     def initialize(schemes = nil)
       schemes = Array(schemes)
       schemes = DEFAULT if schemes.empty?
@@ -12,6 +16,11 @@ module Daijobu
       @current = 0
     end
   
+    # Returns the next scheme object in the stack. Raises Daijobu::NoFallbackScheme when there
+    # are no more schemes.
+    #
+    # And yes, I know it's kind of weird to call this method #next when the first invocation
+    # returns the first scheme, but it made sense at the time.
     def next
       scheme = @schemes[@current]
       raise NoFallbackScheme unless scheme
@@ -19,10 +28,15 @@ module Daijobu
       return scheme
     end
   
+    # Resets the stack of schemes, so that the next invocation of #next returns the first scheme
+    # (I know, I know).
     def reset
       @current = 0
     end
 
+    # Tries the parse (load) the string with each scheme in turn.
+    # Assumes (defensibly) that parsing failed if any non Daijobu::Error exceptions are raised
+    # and moves on to the next scheme.
     def parse(str)
       begin
         obj = self.next.parse(str)
@@ -37,6 +51,9 @@ module Daijobu
       obj
     end
     
+    # Tries the unparse (dump) the string with each scheme in turn.
+    # Assumes (defensibly) that unparsing failed if any non Daijobu::Error exceptions are raised
+    # and moves on to the next scheme.    
     def unparse(obj)
       begin
         str = self.next.unparse(obj)

data/lib/daijobu/schemes/eval.rb

@@ -1,11 +1,17 @@
 module Daijobu
   module Scheme
+    
+    # Daijobu::Scheme::Eval is the serialization for pure Ruby code.
+    # Theoretically, then, anything could be put into and taken out of a key-value-store,
+    # provided that they're always rehydrated into an appropriate binding.
     class Eval
       
+      # Parses by #eval'ing the string.
       def parse(str)
         str.nil? ? nil : eval(str)
       end
       
+      # Unparses by #inspect'ing the object. 
       def unparse(obj)
         obj.inspect
       end

data/lib/daijobu/schemes/json.rb

@@ -2,12 +2,21 @@ require 'json'
 
 module Daijobu
   module Scheme
+    
+    # Daijobu::Scheme::JSON is the serialization for JSON.
+    # Uses the native (C) json gem, which is respectably fast.
     class JSON
       
+      # Parses the string using JSON.parse.
+      # JSON is pretty strict, and it dies whenever the object doesn't have an enclosing
+      # structure (i.e. an array or tuple). You might have problems parsing bare strings,
+      # integers, booleans, and nulls. It's weird, though, because JSON doesn't seem to have
+      # a problem unparsing these things. Just a heads-up.
       def parse(str)
         str.nil? ? nil : ::JSON.parse(str)
       end
       
+      # Unparses the object using JSON.unparse.
       def unparse(obj)
         ::JSON.unparse(obj)
       end

data/lib/daijobu/schemes/marshal.rb

@@ -1,11 +1,15 @@
 module Daijobu
   module Scheme
+    
+    # Daijobu::Scheme::Marshal is the serialization for Ruby binary code.
     class Marshal
       
+      # Parses the string using Marshal.load.
       def parse(str)
         str.nil? ? nil : ::Marshal.load(str)
       end
       
+      # Unparses the object using Marshal.dump.
       def unparse(obj)
         ::Marshal.dump(obj)
       end

data/lib/daijobu/schemes/raw.rb

@@ -1,11 +1,17 @@
 module Daijobu
   module Scheme
+    
+    # Daijobu::Scheme::Raw is the serialization for nothing. Seriously, it doesn't do anything.
+    # It's rather dubious why you'd use this scheme for reading (if you're just going to be reading
+    # as raw, why use this gem at all?), but writing raw is useful sometimes.
     class Raw
-      
+
+      # Doesn't parse anything. Just returns the string.
       def parse(str)
         str
       end
       
+      # Doesn't unparse anything. Just returns the object.
       def unparse(obj)
         obj
       end

data/lib/daijobu/schemes/yaml.rb

@@ -2,12 +2,20 @@ require 'yaml'
 
 module Daijobu
   module Scheme
+    
+    # Daijobu::Scheme::YAML is the serialization for YAML.
+    # Due to the strictness of the JSON module, you'll often have more luck parsing JSON containing 
+    # bare objects (strings, integers, booleans, etc. without an enclosing structure) using YAML
+    # than with JSON, but YAML's a lot slower. That being said, it makes a good fallback scheme to use
+    # when JSON starts dying.
     class YAML
       
+      # Parses the string using YAML.load.
       def parse(str)
         str.nil? ? nil : ::YAML.load(str)
       end
       
+      # Unparses the object using YAML.dump.
       def unparse(obj)
         ::YAML.dump(obj)
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: sander6-daijobu
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Sander Hartlage