sldb 0.1.0

data/README

@@ -0,0 +1,257 @@
+URLS
+
+  http://raa.ruby-lang.org/search.rhtml?search=sldb
+  http://codeforpeople.com/lib/ruby/sldb
+
+ABOUT
+
+  sldb is a multi-thread, multi-process, and nfs safe abstraction of sqlite
+  databases.  the sldb module is a class generator for concrete databases.  the
+  programmer is freed from worrying about 'database locked' errors and
+  transactions are automatically retried using a linear cyclical backoff time.
+  in the case where all access is via the generated class sldb can even detect
+  certain bugs in nfs daemons and auto-recover.  the class is not limited to nfs
+  use whatsover and can be a useful way to use an embedded sql based databases
+  in your ruby code with minimal effort while still providing
+  multi-process/multi-thread concurrency - something which is quite difficult if
+  using the raw sqlite-ruby interface.
+
+AUTHOR
+
+  ara [dot] t [dot] howard [at] noaa [dot] gov
+
+SAMPLES
+
+  <========< sample/a.rb >========>
+
+  ~ > cat sample/a.rb
+
+    require 'sldb'
+    
+    #
+    # use the factory method to specify your database class
+    #
+    DB =
+      SLDB::class {
+        schema 'create table t ( a, b, c )'
+        path 'sldb'
+      }
+    
+    #
+    # create and instance and use it - it will be created and initialized with the
+    # schema on the first use
+    #
+    db = DB::new
+    
+    db.transaction do
+      db.execute 'insert into t values (0,1,2)'
+      db.execute('select * from t'){|tuple| p tuple}
+    end
+    
+
+  ~ > ruby sample/a.rb
+
+    ["0", "1", "2"]
+
+
+  <========< sample/b.rb >========>
+
+  ~ > cat sample/b.rb
+
+    require 'csv'
+    require 'sldb'
+    
+    DB = SLDB::class :schema => 'create table t ( a, b, c )'
+    db = DB::new 'sldb'
+    
+    #
+    # sldb uses arrayfields so many operations are natural since tuples are arrays,
+    # yet can be indexed by field
+    #
+    db.transaction do
+      db.execute "insert into t values ( 'A', 'B', 'C' )"
+      db.execute('select * from t') do |tuple| 
+        puts "tuple => #{ tuple.inspect }"
+        tuple.fields.each{|f| puts "  tuple[#{ f }] => #{ tuple[f] }"}
+      end
+    end
+    
+    puts
+    
+    #
+    # csv generation is an example of something which is much more natural with
+    # arrays
+    #
+    CSV::generate('csv') do |csv|
+      db.ro_transaction{db.execute('select * from t'){|t| csv << t}}
+    end
+    puts(IO::read('csv'))
+    
+
+  ~ > ruby sample/b.rb
+
+    tuple => ["A", "B", "C"]
+      tuple[a] => A
+      tuple[b] => B
+      tuple[c] => C
+    
+    A,B,C
+
+
+  <========< sample/c.rb >========>
+
+  ~ > cat sample/c.rb
+
+    require 'yaml'
+    require 'sldb'
+    
+    DB = SLDB::new { 
+      schema <<-sql
+        create table t0 ( a, b, c);
+        create table t1 ( x, y, z);
+      sql
+    
+      path 'sldb'
+    }
+    
+    db = DB::new
+    
+    #
+    # many utility methods exist to make working with the databases easier
+    #
+    db.transaction do
+      db.tablenames.each do |tablename|
+        tuple = db.tuple_for tablename
+        tuple.fields.each{|f| tuple[f] = db.timestamp 'local' => true}
+        values = db.quote tuple
+        sql = "insert into #{ tablename } values (#{ values.join ',' })"
+        db.execute sql
+      end
+    end
+    
+    db.read_only_transaction do
+      db.tablenames.each do |tablename|
+        db.execute("select * from #{ tablename }") do |t|
+          t.map!{|f| db.stamptime f, 'local' => true}
+          y t.to_hash
+        end
+      end
+    end
+
+  ~ > ruby sample/c.rb
+
+    --- 
+    a: 2005-05-13 14:13:40.754680 -06:00
+    b: 2005-05-13 14:13:40.754882 -06:00
+    c: 2005-05-13 14:13:40.754910 -06:00
+    --- 
+    x: 2005-05-13 14:13:40.755928 -06:00
+    y: 2005-05-13 14:13:40.755980 -06:00
+    z: 2005-05-13 14:13:40.756005 -06:00
+
+
+  <========< sample/d.rb >========>
+
+  ~ > cat sample/d.rb
+
+    require 'yaml'
+    require 'sldb'
+    
+    DB = SLDB::new { schema 'create table t ( tid, time )'; path 'sldb' }
+    db = DB::new
+    
+    #
+    # multi-processed/multi-threaded applications may simoultaneously access the db 
+    #
+    
+    4.times do
+      unless fork
+        pid = $$
+        threads = []
+        2.times do |i|
+          threads << 
+            Thread::new(i, db) do |tid, db|
+              sleep rand
+              tuple = db.tuple_for 't'
+              tuple['tid'] = "#{ pid }:#{ tid }" 
+              tuple['time'] = Time::now.to_f
+              values = db.quote tuple
+              db.transaction{db.execute "insert into t values(#{ values.join ',' })"}
+            end
+        end
+        threads.each{|t| t.join}
+        exit
+      end
+    end
+    
+    4.times{ Process::wait }
+    
+    report = Hash::new{|h,k| h[k] = []} 
+    
+    db.transaction{db.execute("select * from t"){|t| report['t'] << t.to_hash}}
+    
+    y report
+
+  ~ > ruby sample/d.rb
+
+    --- 
+    t: 
+      - 
+        time: "1116015221.16824"
+        tid: 9697:1
+      - 
+        time: "1116015221.2326"
+        tid: 9697:0
+      - 
+        time: "1116015221.64353"
+        tid: 9696:0
+      - 
+        time: "1116015221.83744"
+        tid: 9695:0
+      - 
+        time: "1116015221.85167"
+        tid: 9695:1
+      - 
+        time: "1116015222.25714"
+        tid: 9698:0
+      - 
+        time: "1116015222.27658"
+        tid: 9698:1
+      - 
+        time: "1116015221.81659"
+        tid: 9696:1
+
+
+  <========< sample/e.rb >========>
+
+  ~ > cat sample/e.rb
+
+    require 'sldb'
+    
+    #
+    # the SLDB factory method handles - as a special case - a pathname being passed
+    # in as meaning : create the class AND give me and instance of it which allows
+    # connecting to dbs even when the schema is unknown
+    #
+    
+    dbklass = SLDB::new 'schema' => 'create table t ( answer )', 
+                        'path'  => 'sldb'
+    db = dbklass::new
+    db.transaction{ db.execute 'insert into t values ( 42 )' }
+    
+    fork do
+      db = SLDB::new 'sldb'  # here we don't know schema
+      db.transaction{ db.execute('select * from t'){|t| puts t['answer']}}
+    end
+    
+    Process::wait
+
+  ~ > ruby sample/e.rb
+
+    42
+
+
+CAVEATS
+
+  this library is __highly__ experimental and subject to change.
+

data/README.tmpl

@@ -0,0 +1,30 @@
+URLS
+
+  http://raa.ruby-lang.org/search.rhtml?search=sldb
+  http://codeforpeople.com/lib/ruby/sldb
+
+ABOUT
+
+  sldb is a multi-thread, multi-process, and nfs safe abstraction of sqlite
+  databases.  the sldb module is a class generator for concrete databases.  the
+  programmer is freed from worrying about 'database locked' errors and
+  transactions are automatically retried using a linear cyclical backoff time.
+  in the case where all access is via the generated class sldb can even detect
+  certain bugs in nfs daemons and auto-recover.  the class is not limited to nfs
+  use whatsover and can be a useful way to use an embedded sql based databases
+  in your ruby code with minimal effort while still providing
+  multi-process/multi-thread concurrency - something which is quite difficult if
+  using the raw sqlite-ruby interface.
+
+AUTHOR
+
+  ara [dot] t [dot] howard [at] noaa [dot] gov
+
+SAMPLES
+
+@samples
+
+CAVEATS
+
+  this library is __highly__ experimental and subject to change.
+

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/gemspec.rb

@@ -0,0 +1,23 @@
+lib, version = File::basename(File::dirname(File::expand_path(__FILE__))).split %r/-/, 2
+
+require 'rubygems'
+
+Gem::Specification::new do |spec|
+  spec.name = lib 
+  spec.version = version 
+  spec.platform = Gem::Platform::RUBY
+  spec.summary = lib 
+
+  spec.files = Dir::glob "**/**"
+  spec.executables = Dir::glob("bin/*").map{|exe| File::basename exe}
+  
+  spec.require_path = "lib" 
+  spec.autorequire = lib
+
+  spec.has_rdoc = File::exist? "doc" 
+  spec.test_suite_file = "test/#{ lib }.rb" if File::directory? "test"
+
+  spec.author = "Ara T. Howard"
+  spec.email = "ara.t.howard@noaa.gov"
+  spec.homepage = "http://codeforpeople.com/lib/ruby/#{ lib }/"
+end

data/gen_readme.rb

@@ -0,0 +1,26 @@
+$VERBOSE=nil
+def indent s, n = 2
+  ws = ' ' * n
+  s.gsub %r/^/, ws 
+end
+
+template = IO::read 'README.tmpl'
+
+samples = ''
+prompt = '~ > '
+
+Dir['sample/*'].each do |sample|
+  samples << "\n" << "  <========< #{ sample } >========>" << "\n\n"
+  cmd = "cat #{ sample }" 
+  samples << indent(prompt + cmd, 2) << "\n\n" 
+  samples << indent(`#{ cmd }`, 4) << "\n" 
+  cmd = "ruby #{ sample }" 
+  samples << indent(prompt + cmd, 2) << "\n\n" 
+  cmd = "rm -rf ./sldb; rm -rf csv; ruby -I ./lib #{ sample }" 
+  samples << indent(`#{ cmd }`, 4) << "\n" 
+end
+
+#samples.gsub! %r/^/, '  '
+
+readme  = template.gsub %r/^\s*@samples\s*$/, samples
+print readme 

data/install.rb

@@ -0,0 +1,206 @@
+#!/usr/bin/env ruby
+require 'rbconfig'
+require 'find'
+require 'ftools'
+require 'tempfile'
+include Config
+
+LIBDIR      = "lib"
+LIBDIR_MODE = 0644
+
+BINDIR      = "bin"
+BINDIR_MODE = 0755
+
+
+$srcdir            = CONFIG["srcdir"]
+$version           = CONFIG["MAJOR"]+"."+CONFIG["MINOR"]
+$libdir            = File.join(CONFIG["libdir"], "ruby", $version)
+$archdir           = File.join($libdir, CONFIG["arch"])
+$site_libdir       = $:.find {|x| x =~ /site_ruby$/}
+$bindir            = CONFIG["bindir"] || CONFIG['BINDIR']
+$ruby_install_name = CONFIG['ruby_install_name'] || CONFIG['RUBY_INSTALL_NAME'] || 'ruby'
+$ruby_ext          = CONFIG['EXEEXT'] || ''
+$ruby              = File.join($bindir, ($ruby_install_name + $ruby_ext))
+
+if !$site_libdir
+  $site_libdir = File.join($libdir, "site_ruby")
+elsif $site_libdir !~ %r/#{Regexp.quote($version)}/
+  $site_libdir = File.join($site_libdir, $version)
+end
+
+def install_rb(srcdir=nil, destdir=nil, mode=nil, bin=nil)
+#{{{
+  path   = []
+  dir    = []
+  Find.find(srcdir) do |f|
+    next unless FileTest.file?(f)
+    next if (f = f[srcdir.length+1..-1]) == nil
+    next if (/CVS$/ =~ File.dirname(f))
+    next if f =~ %r/\.lnk/
+    path.push f
+    dir |= [File.dirname(f)]
+  end
+  for f in dir
+    next if f == "."
+    next if f == "CVS"
+    File::makedirs(File.join(destdir, f))
+  end
+  for f in path
+    next if (/\~$/ =~ f)
+    next if (/^\./ =~ File.basename(f))
+    unless bin
+      File::install(File.join(srcdir, f), File.join(destdir, f), mode, true)
+    else
+      from = File.join(srcdir, f)
+      to = File.join(destdir, f)
+      shebangify(from) do |sf|
+        $deferr.print from, " -> ", File::catname(from, to), "\n"
+        $deferr.printf "chmod %04o %s\n", mode, to 
+        File::install(sf, to, mode, false)
+      end
+    end
+  end
+#}}}
+end
+def shebangify f
+#{{{
+  open(f) do |fd|
+    buf = fd.read 42 
+    if buf =~ %r/^\s*#\s*!.*ruby/o
+      ftmp = Tempfile::new("#{ $$ }_#{ File::basename(f) }")
+      begin
+        fd.rewind
+        ftmp.puts "#!#{ $ruby  }"
+        while((buf = fd.read(8192)))
+          ftmp.write buf
+        end
+        ftmp.close
+        yield ftmp.path
+      ensure
+        ftmp.close!
+      end
+    else
+      yield f
+    end
+  end
+#}}}
+end
+def ARGV.switch
+#{{{
+  return nil if self.empty?
+  arg = self.shift
+  return nil if arg == '--'
+  if arg =~ /^-(.)(.*)/
+    return arg if $1 == '-'
+    raise 'unknown switch "-"' if $2.index('-')
+    self.unshift "-#{$2}" if $2.size > 0
+    "-#{$1}"
+  else
+    self.unshift arg
+    nil
+  end
+#}}}
+end
+def ARGV.req_arg
+#{{{
+  self.shift || raise('missing argument')
+#}}}
+end
+def linkify d, linked = []
+#--{{{
+  if test ?d, d
+    versioned = Dir[ File::join(d, "*-[0-9].[0-9].[0-9].rb") ]
+    versioned.each do |v| 
+      src, dst = v, v.gsub(%r/\-[\d\.]+\.rb$/, '.rb')
+      lnk = nil
+      begin
+        if test ?l, dst
+          lnk = "#{ dst }.lnk"
+          puts "#{ dst } -> #{ lnk }"
+          File::rename dst, lnk
+        end
+        unless test ?e, dst
+          puts "#{ src } -> #{ dst }"
+          File::copy src, dst 
+          linked << dst
+        end
+      ensure
+        if lnk
+          at_exit do
+            puts "#{ lnk } -> #{ dst }"
+            File::rename lnk, dst
+          end
+        end
+      end
+    end
+  end
+  linked
+#--}}}
+end
+
+
+#
+# main program
+#
+
+libdir = $site_libdir
+bindir = $bindir
+no_linkify = false
+linked = nil
+help = false
+
+usage = <<-usage
+  #{ File::basename $0 }
+    -d, --destdir    <destdir>
+    -l, --libdir     <libdir>
+    -b, --bindir     <bindir>
+    -r, --ruby       <ruby>
+    -n, --no_linkify
+    -s, --sudo
+    -h, --help
+usage
+
+begin
+  while switch = ARGV.switch
+    case switch
+    when '-d', '--destdir'
+      libdir = ARGV.req_arg
+    when '-l', '--libdir'
+      libdir = ARGV.req_arg
+    when '-b', '--bindir'
+      bindir = ARGV.req_arg
+    when '-r', '--ruby'
+      $ruby = ARGV.req_arg
+    when '-n', '--no_linkify'
+      no_linkify = true
+    when '-s', '--sudo'
+      sudo = 'sudo' 
+    when '-h', '--help'
+      help = true
+    else
+      raise "unknown switch #{switch.dump}"
+    end
+  end
+rescue
+  STDERR.puts $!.to_s
+  STDERR.puts usage
+  exit 1
+end    
+
+if help
+  STDOUT.puts usage
+  exit
+end
+
+unless no_linkify
+  linked = linkify('lib') + linkify('bin')
+end
+
+system "#{ $ruby } extconf.rb && make && #{ sudo } make install" if test(?s, 'extconf.rb')
+
+install_rb(LIBDIR, libdir, LIBDIR_MODE)
+install_rb(BINDIR, bindir, BINDIR_MODE, bin=true)
+
+if linked
+  linked.each{|path| File::rm_f path}
+end