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