«

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 ath => '/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 ld => 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}
{ld=>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