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