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