NAME
   state

SYNOPSIS
   platform agnostic persistent state for ruby processes based on sqlite

DESCRIPTION
   state provides an extremely simple to use state mechanism for ruby  
programs
   which require state between invocations.  the storage is based on  
sqlite and
   is therefore platform agnostic.  using state is no more difficult  
that using
   a hash - only that hash will persist between invocations your ruby  
program.
   see the samples and specs for details.

INSTALL
   gem install state

URIS
   http://codeforpeople.com/lib/ruby/
   http://rubyforge.org/projects/codeforpeople/

SAMPLES

   <========< sample/a.rb >========>

   ~ > cat sample/a.rb

     require 'state'

     # state provides persistent state for processes.  usage requires  
simply
     # accesses the state in a hash-like way.
     #

     # one process can create state
     #
       child do
         State.clear
         State['key'] = 'value'
       end

     # and later processes can have access to it
     #
       2.times do |i|
         child do
           value = State['key']
           puts "child[#{ i }] => #{ value.inspect }"
         end
       end


     BEGIN {
       # we use fork just for demonstation, but this works on windows  
too ;-)
       #
         def child &block
           Process.waitpid fork(&block)
         end
     }


   ~ > ruby sample/a.rb

     child[0] => "value"
     child[1] => "value"


   <========< sample/b.rb >========>

   ~ > cat sample/b.rb

     require 'state'

     # state will store it's db in a subdirectory (.state) of your  
home directory,
     # the default database is ~/.state/global, but you may specify a  
name to
     # create a new database
     #

       db = State.for 'foobar'

       db.clear

       puts db.path

       10.times{|i| db[i] = i}

       puts db.keys.inspect

   ~ > ruby sample/b.rb

     /Users/ahoward/.state/foobar
     [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]


   <========< sample/c.rb >========>

   ~ > cat sample/c.rb

     require 'state'

     # of course you can specify and absolute path
     #

       db = State.for :path => '/tmp/state'

       db.clear

       puts db.path

   ~ > ruby sample/c.rb

     /tmp/state


   <========< sample/d.rb >========>

   ~ > cat sample/d.rb

     require 'state'

     # in general the interface for state is like that of a hash, see  
the specs for
     # more details

       db = State.for 'foobar'

       db.clear

       10.times{|i| db[i] = i**2}
       5.times{|i| db.delete i}

       p db.keys
       p db.values

     # use the update method for atomic read-update of a key/val pair

       db['key'] = 42

       p :current => db['key']

       db.update 'key' do |old|
         p :old => old
         new = 42.0
       end

       p :update => db['key']



   ~ > ruby sample/d.rb

     [5, 6, 7, 8, 9]
     [25, 36, 49, 64, 81]
     {:current=>42}
     {:old=>42}
     {:update=>42.0}


HISTORY
   0.4.2
     initial version

AUTHORS
   ara.t.howard




a @ http://codeforpeople.com/
--
we can deny everything, except that we have the possibility of being  
better. simply reflect on that.
h.h. the 14th dalai lama