rufus-tokyo 0.1.2 → 0.1.3

data/lib/rufus/tokyo/cabinet.rb

@@ -0,0 +1,3 @@
+
+require 'rufus/tokyo/cabinet/abstract'
+

data/lib/rufus/tokyo/cabinet/abstract.rb

@@ -0,0 +1,237 @@
+#
+#--
+# Copyright (c) 2009, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#++
+#
+
+#
+# "made in Japan"
+#
+# jmettraux@gmail.com
+#
+
+require 'rufus/tokyo/hmethods'
+require 'rufus/tokyo/cabinet/lib'
+
+
+module Rufus::Tokyo
+
+  #
+  # A 'cabinet', ie a Tokyo Cabinet [abstract] database.
+  #
+  # Follows the abstract API described at :
+  #
+  #   http://tokyocabinet.sourceforge.net/spex-en.html#tcadbapi
+  #
+  # An usage example :
+  #
+  #   db = Rufus::Tokyo::Cabinet.new('test_data.tch')
+  #   db['pillow'] = 'Shonagon'
+  #
+  #   db.size # => 1
+  #   db['pillow'] # => 'Shonagon'
+  #
+  #   db.delete('pillow') # => 'Shonagon'
+  #   db.size # => 0
+  #
+  #   db.close
+  #
+  class Cabinet
+    include CabinetLibMixin
+    include HashMethods
+    include Enumerable
+
+    #
+    # Creates/opens the cabinet, raises an exception in case of
+    # creation/opening failure.
+    #
+    # This method accepts a 'name' parameter and an optional 'params' hash
+    # parameter.
+    #
+    # 'name' follows the syntax described at
+    #
+    #   http://tokyocabinet.sourceforge.net/spex-en.html#tcadbapi
+    #
+    # under tcadbopen(). For example :
+    #
+    #   db = Rufus::Tokyo::Cabinet.new('casket.tch#bnum=100000#opts=ld')
+    #
+    # will open (eventually create) a hash database backed in the file
+    # 'casket.tch' with a bucket number of 100000 and the 'large' and
+    # 'deflate' options (opts) turned on.
+    #
+    # == :hash or :tree
+    #
+    # Setting the name to :hash or :tree simply will create a in-memory hash
+    # or tree respectively (see #new_tree and #new_hash).
+    #
+    # == tuning parameters
+    #
+    # It's ok to use the optional params hash to pass tuning parameters and
+    # options, thus
+    #
+    #   db = Rufus::Tokyo::Cabinet.new('casket.tch#bnum=100000#opts=ld')
+    #
+    # and
+    #
+    #   db = Rufus::Tokyo::Cabinet.new(
+    #     'casket.tch', :bnum => 100000, :opts => 'ld')
+    #
+    # are equivalent.
+    #
+    # == mode
+    #
+    # To open a db in read-only mode :
+    #
+    #   db = Rufus::Tokyo::Cabinet.new('casket.tch#mode=r')
+    #   db = Rufus::Tokyo::Cabinet.new('casket.tch', :mode => 'r')
+    #
+    def initialize (name, params={})
+
+      @db = lib.tcadbnew
+
+      name = '*' if name == :hash # in memory hash database
+      name = '+' if name == :tree # in memory B+ tree database
+
+      name = name + params.collect { |k, v| "##{k}=#{v}" }.join('')
+
+      (lib.tcadbopen(@db, name) == 1) ||
+        raise("failed to open/create db '#{name}'")
+
+      self.default = params[:default]
+      @default_proc ||= params[:default_proc]
+    end
+
+    #
+    # Returns a new in-memory hash. Accepts the same optional params hash
+    # as new().
+    #
+    def self.new_hash (params={})
+      self.new(:hash, params)
+    end
+
+    #
+    # Returns a new in-memory B+ tree. Accepts the same optional params hash
+    # as new().
+    #
+    def self.new_tree (params={})
+      self.new(:tree, params)
+    end
+
+    #
+    # No comment
+    #
+    def []= (k, v)
+      lib.tcadbput2(@db, k, v)
+    end
+
+    #
+    # (The actual #[] method is provided by HashMethods
+    #
+    def get (k)
+      lib.tcadbget2(@db, k) rescue nil
+    end
+    protected :get
+
+    #
+    # Removes a record from the cabinet, returns the value if successful
+    # else nil.
+    #
+    def delete (k)
+      v = self[k]
+      (lib.tcadbout2(@db, k) == 1) ? v : nil
+    end
+
+    #
+    # Returns the number of records in the 'cabinet'
+    #
+    def size
+      lib.tcadbrnum(@db)
+    end
+
+    #
+    # Removes all the records in the cabinet (use with care)
+    #
+    # Returns self (like Ruby's Hash does).
+    #
+    def clear
+      lib.tcadbvanish(@db)
+      self
+    end
+
+    #
+    # Returns the 'weight' of the db (in bytes)
+    #
+    def weight
+      lib.tcadbsize(@db)
+    end
+
+    #
+    # Closes the cabinet (and frees the datastructure allocated for it),
+    # returns true in case of success.
+    #
+    def close
+      result = lib.tcadbclose(@db)
+      lib.tcadbdel(@db)
+      (result == 1)
+    end
+
+    #
+    # Copies the current cabinet to a new file.
+    #
+    # Returns true if it was successful.
+    #
+    def copy (target_path)
+      (lib.tcadbcopy(@db, target_path) == 1)
+    end
+
+    #
+    # Copies the current cabinet to a new file.
+    #
+    # Does it by copying each entry afresh to the target file. Spares some
+    # space, hence the 'compact' label...
+    #
+    def compact_copy (target_path)
+      @other_db = Rufus::Tokyo::Cabinet.new(target_path)
+      self.each { |k, v| @other_db[k] = v }
+      @other_db.close
+    end
+
+    #
+    # "synchronize updated contents of an abstract database object with
+    # the file and the device"
+    #
+    def sync
+      (lib.tcadbsync(@db) == 1)
+    end
+
+    #
+    # Returns an array with all the keys in the databse
+    #
+    def keys
+      a = []
+      lib.tcadbiterinit(@db)
+      while (k = (lib.tcadbiternext2(@db) rescue nil)); a << k; end
+      a
+    end
+  end
+end
+

data/lib/rufus/tokyo/cabinet/lib.rb

@@ -0,0 +1,179 @@
+#
+#--
+# Copyright (c) 2009, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#++
+#
+
+#
+# "made in Japan"
+#
+# jmettraux@gmail.com
+#
+
+require 'rufus/tokyo/base'
+
+
+module Rufus::Tokyo
+
+  #
+  # The libtokyocabinet.so methods get bound to this module
+  #
+  module CabinetLib #:nodoc#
+    extend FFI::Library
+
+    Rufus::Tokyo.generate_lib_mixin(self)
+      # module Rufus::Tokyo::CabinetLibMixin
+
+    #
+    # find Tokyo Cabinet lib
+
+    paths = Array(ENV['TOKYO_CABINET_LIB'] || %w{
+      /opt/local/lib/libtokyocabinet.dylib
+      /usr/local/lib/libtokyocabinet.dylib
+      /usr/local/lib/libtokyocabinet.so
+    })
+
+    ffi_lib(paths.find { |path| File.exist?(path) })
+
+    #
+    # maybe put that in a standalone c_lib.rb
+
+    # length of a string
+    #
+    attach_function :strlen, [ :string ], :int
+
+    # frees a mem zone (TC style)
+    #
+    attach_function :tcfree, [ :pointer ], :void
+
+    #
+    # tcadb functions
+    #
+    # http://tokyocabinet.sourceforge.net/spex-en.html#tcadbapi
+
+    attach_function :tcadbnew, [], :pointer
+
+    attach_function :tcadbopen, [ :pointer, :string ], :int
+    attach_function :tcadbclose, [ :pointer ], :int
+
+    attach_function :tcadbdel, [ :pointer ], :void
+
+    attach_function :tcadbrnum, [ :pointer ], :uint64
+    attach_function :tcadbsize, [ :pointer ], :uint64
+
+    attach_function :tcadbput2, [ :pointer, :string, :string ], :int
+    attach_function :tcadbget2, [ :pointer, :string ], :string
+    attach_function :tcadbout2, [ :pointer, :string ], :int
+
+    attach_function :tcadbiterinit, [ :pointer ], :int
+    attach_function :tcadbiternext2, [ :pointer ], :string
+
+    attach_function :tcadbvanish, [ :pointer ], :int
+
+    attach_function :tcadbsync, [ :pointer ], :int
+    attach_function :tcadbcopy, [ :pointer, :string ], :int
+
+    #
+    # tctdb functions
+    #
+    # http://tokyocabinet.sourceforge.net/spex-en.html#tctdbapi
+
+    attach_function :tctdbnew, [], :pointer
+
+    attach_function :tctdbopen, [ :pointer, :string, :int ], :int
+
+    attach_function :tctdbgenuid, [ :pointer ], :int64
+
+    attach_function :tctdbget, [ :pointer, :string, :int ], :pointer
+
+    attach_function :tctdbput, [ :pointer, :string, :int, :pointer ], :int
+    attach_function :tctdbput3, [ :pointer, :string, :string ], :int
+    attach_function :tctdbout2, [ :pointer, :string ], :int
+
+    attach_function :tctdbecode, [ :pointer ], :int
+    attach_function :tctdberrmsg, [ :int ], :string
+
+    attach_function :tctdbclose, [ :pointer ], :int
+    attach_function :tctdbdel, [ :pointer ], :void
+
+    attach_function :tctdbrnum, [ :pointer ], :uint64
+
+    attach_function :tctdbvanish, [ :pointer ], :int
+
+    #
+    # tctdbqry functions
+    #
+    # http://tokyocabinet.sourceforge.net/spex-en.html#tctdbapi
+
+    attach_function :tctdbqrynew, [ :pointer ], :pointer
+    attach_function :tctdbqrydel, [ :pointer ], :void
+
+    attach_function :tctdbqryaddcond, [ :pointer, :string, :int, :string ], :void
+    attach_function :tctdbqrysetorder, [ :pointer, :string, :int ], :void
+    attach_function :tctdbqrysetmax, [ :pointer, :int ], :void
+
+    attach_function :tctdbqrysearch, [ :pointer ], :pointer
+
+    attach_function :tctdbqrydel, [ :pointer ], :void
+
+    #
+    # tcmap functions
+    #
+    # http://tokyocabinet.sourceforge.net/spex-en.html#tcutilapi
+
+    attach_function :tcmapnew, [], :pointer
+
+    attach_function :tcmapput2, [ :pointer, :string, :string ], :void
+    attach_function :tcmapout2, [ :pointer, :string ], :int
+    attach_function :tcmapclear, [ :pointer ], :void
+
+    attach_function :tcmapdel, [ :pointer ], :void
+
+    attach_function :tcmapget2, [ :pointer, :string ], :string
+
+    attach_function :tcmapiterinit, [ :pointer ], :void
+    attach_function :tcmapiternext2, [ :pointer ], :string
+
+    attach_function :tcmaprnum, [ :pointer ], :uint64
+
+    #
+    # tclist functions
+    #
+    # http://tokyocabinet.sourceforge.net/spex-en.html#tcutilapi
+
+    attach_function :tclistnew, [], :pointer
+
+    attach_function :tclistnum, [ :pointer ], :int
+    attach_function :tclistval2, [ :pointer, :int ], :string
+
+    attach_function :tclistpush2, [ :pointer, :string ], :void
+    attach_function :tclistpop2, [ :pointer ], :string
+    attach_function :tclistshift2, [ :pointer ], :string
+    attach_function :tclistunshift2, [ :pointer, :string ], :void
+    attach_function :tclistover2, [ :pointer, :int, :string ], :void
+
+    attach_function :tclistremove2, [ :pointer, :int ], :string
+      # beware, seems like have to free the return string self
+
+    attach_function :tclistdel, [ :pointer ], :void
+  end
+end
+

data/lib/rufus/tokyo/cabinet/table.rb

@@ -0,0 +1,528 @@
+#
+#--
+# Copyright (c) 2009, John Mettraux, jmettraux@gmail.com
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#++
+#
+
+#
+# "made in Japan"
+#
+# jmettraux@gmail.com
+#
+
+require 'rufus/tokyo/cabinet/lib'
+require 'rufus/tokyo/cabinet/util'
+
+
+module Rufus::Tokyo
+
+  #
+  # A 'table' a table database.
+  #
+  #   http://alpha.mixi.co.jp/blog/?p=290
+  #   http://tokyocabinet.sourceforge.net/spex-en.html#tctdbapi
+  #
+  # A short example :
+  #
+  #   require 'rubygems'
+  #   require 'rufus/tokyo/cabinet/table'
+  #
+  #   t = Rufus::Tokyo::Table.new('table.tdb', :create, :write)
+  #     # '.tdb' suffix is a must
+  #
+  #   t['pk0'] = { 'name' => 'alfred', 'age' => '22' }
+  #   t['pk1'] = { 'name' => 'bob', 'age' => '18' }
+  #   t['pk2'] = { 'name' => 'charly', 'age' => '45' }
+  #   t['pk3'] = { 'name' => 'doug', 'age' => '77' }
+  #   t['pk4'] = { 'name' => 'ephrem', 'age' => '32' }
+  #
+  #   p t.query { |q|
+  #     q.add_condition 'age', :numge, '32'
+  #     q.order_by 'age'
+  #     q.limit 2
+  #   }
+  #     # => [ {"name"=>"ephrem", :pk=>"pk4", "age"=>"32"},
+  #     #      {"name"=>"charly", :pk=>"pk2", "age"=>"45"} ]
+  #
+  #   t.close
+  #
+  class Table
+    include CabinetLibMixin
+    include TokyoContainerMixin
+
+    #
+    # Creates a Table instance (creates or opens it depending on the args)
+    #
+    # For example,
+    #
+    #   t = Rufus::Tokyo::Table.new('table.tdb', :create, :write)
+    #     # '.tdb' suffix is a must
+    #
+    # will create the table.tdb (or simply open it if already present)
+    # and make sure we have write access to it.
+    # Note that the suffix (.tdc) is relevant to Tokyo Cabinet, using another
+    # will result in a Tokyo Cabinet error.
+    #
+    def initialize (*args)
+
+      path = args.first # car
+      params = args[1..-1] # cdr
+
+      mode = compute_open_mode(params)
+
+      @db = self.lib.tctdbnew
+
+      (lib.tctdbopen(@db, path, compute_open_mode(params)) == 1 ) || raise_error
+    end
+
+    #
+    # Closes the table (and frees the datastructure allocated for it),
+    # returns true in case of success.
+    #
+    def close
+      result = lib.tctdbclose(@db)
+      lib.tctdbdel(@db)
+      (result == 1)
+    end
+
+    #
+    # Generates a unique id (in the context of this Table instance)
+    #
+    def generate_unique_id
+      lib.tctdbgenuid(@db)
+    end
+    alias :genuid :generate_unique_id
+
+    #
+    # Accepts a variable number of arguments, at least two. First one
+    # is the primary key of the record, the others are the columns.
+    #
+    # One can also directly write
+    #
+    #   table['one'] = [ 'name', 'toto', 'age', '33' ]
+    #   table['two'] = [ 'name', 'fred', 'age', '45' ]
+    #
+    # instead of
+    #
+    #   table.tabbed_put('one', 'name', 'toto', 'age', '33')
+    #   table.tabbed_put('two', 'name', 'fred', 'age', '45')
+    #
+    # beware : inserting an array uses a tab separator...
+    #
+    def tabbed_put (pk, *args)
+
+      cols = args.collect { |e| e.to_s }.join("\t")
+
+      (lib.tctdbput3(@db, pk, cols) == 1) || raise_error
+
+      args
+    end
+
+    #
+    # Inserts a record in the table db
+    #
+    #   table['pk0'] = [ 'name', 'fred', 'age', '45' ]
+    #   table['pk1'] = { 'name' => 'jeff', 'age' => '46' }
+    #
+    def []= (pk, h_or_a)
+
+      return tabbed_put(pk, *h_or_a) if h_or_a.is_a?(Array)
+
+      pklen = lib.strlen(pk)
+
+      m = Rufus::Tokyo::Map.from_h(h_or_a)
+
+      r = lib.tctdbput(@db, pk, pklen, m.pointer)
+
+      m.free
+
+      (r == 1) || raise_error
+
+      h_or_a
+    end
+
+    #
+    # Removes an entry in the table
+    #
+    # (might raise an error if the delete itself failed, but returns nil
+    # if there was no entry for the given key)
+    #
+    def delete (k)
+      v = self[k]
+      return nil unless v
+      (lib.tctdbout2(@db, k) == 1) || raise_error
+      v
+    end
+
+    #
+    # Removes all records in this table database
+    #
+    def clear
+      (lib.tctdbvanish(@db) == 1) || raise_error
+    end
+
+    #
+    # Returns the value (as a Ruby Hash) else nil
+    #
+    def [] (k)
+      m = lib.tctdbget(@db, k, lib.strlen(k))
+      return nil if m.address == 0 # :( too bad, but it works
+      Rufus::Tokyo::Map.to_h(m) # which frees the map
+    end
+
+    #
+    # Returns the number of records in this table db
+    #
+    def size
+      lib.tctdbrnum(@db)
+    end
+
+    #
+    # Prepares a query instance (block is optional)
+    #
+    def prepare_query (&block)
+      q = TableQuery.new(self)
+      block.call(q) if block
+      q
+    end
+
+    #
+    # Prepares and runs a query, returns a ResultSet instance
+    # (takes care of freeing the query structure)
+    #
+    def do_query (&block)
+      q = prepare_query(&block)
+      rs = q.run
+      q.free
+      rs
+    end
+
+    #
+    # Prepares and runs a query, returns an array of hashes (all Ruby)
+    # (takes care of freeing the query and the result set structures)
+    #
+    def query (&block)
+      rs = do_query(&block)
+      a = rs.to_a
+      rs.free
+      a
+    end
+
+    #
+    # Returns the actual pointer to the Tokyo Cabinet table
+    #
+    def pointer
+      @db
+    end
+
+    protected
+
+    #
+    # Obviously something got wrong, let's ask the db about it and raise
+    # a TokyoError
+    #
+    def raise_error
+
+      err_code = lib.tctdbecode(@db)
+      err_msg = lib.tctdberrmsg(err_code)
+
+      raise TokyoError, "(err #{err_code}) #{err_msg}"
+    end
+  end
+
+  #
+  # A query on a Tokyo Cabinet table db
+  #
+  class TableQuery
+    include CabinetLibMixin
+
+    OPERATORS = {
+
+      # strings...
+
+      :streq => 0, # string equality
+      :eq => 0,
+      :eql => 0,
+      :equals => 0,
+
+      :strinc => 1, # string include
+      :inc => 1, # string include
+      :includes => 1, # string include
+
+      :strbw => 2, # string begins with
+      :bw => 2,
+      :starts_with => 2,
+      :strew => 3, # string ends with
+      :ew => 3,
+      :ends_with => 3,
+
+      :strand => 4, # string which include all the tokens in the given exp
+      :and => 4,
+
+      :stror => 5, # string which include at least one of the tokens
+      :or => 5,
+
+      :stroreq => 6, # string which is equal to at least one token
+
+      :strorrx => 7, # string which matches the given regex
+      :regex => 7,
+      :matches => 7,
+
+      # numbers...
+
+      :numeq => 8, # equal
+      :numequals => 8,
+      :numgt => 9, # greater than
+      :gt => 9,
+      :numge => 10, # greater or equal
+      :ge => 10,
+      :gte => 10,
+      :numlt => 11, # greater or equal
+      :lt => 11,
+      :numle => 12, # greater or equal
+      :le => 12,
+      :lte => 12,
+      :numbt => 13, # a number between two tokens in the given exp
+      :bt => 13,
+      :between => 13,
+
+      :numoreq => 14 # number which is equal to at least one token
+    }
+
+    TDBQCNEGATE = 1 << 24
+    TDBQCNOIDX = 1 << 25
+
+    DIRECTIONS = {
+      :strasc => 0,
+      :strdesc => 1,
+      :asc => 0,
+      :desc => 1,
+      :numasc => 2,
+      :numdesc => 3
+    }
+
+    #
+    # Creates a query for a given Rufus::Tokyo::Table
+    #
+    # Queries are usually created via the #query (#prepare_query #do_query)
+    # of the Table instance.
+    #
+    # Methods of interest here are :
+    #
+    #   * #add (or #add_condition)
+    #   * #order_by
+    #   * #limit
+    #
+    # also
+    #
+    #   * #pk_only
+    #   * #no_pk
+    #
+    def initialize (table)
+      @table = table
+      @query = lib.tctdbqrynew(@table.pointer)
+      @opts = {}
+    end
+
+    #
+    # Adds a condition
+    #
+    #   table.query { |q|
+    #     q.add 'name', :equals, 'Oppenheimer'
+    #     q.add 'age', :numgt, 35
+    #   }
+    #
+    # Understood 'operators' :
+    #
+    #   :streq # string equality
+    #   :eq
+    #   :eql
+    #   :equals
+    #
+    #   :strinc # string include
+    #   :inc # string include
+    #   :includes # string include
+    #
+    #   :strbw # string begins with
+    #   :bw
+    #   :starts_with
+    #   :strew # string ends with
+    #   :ew
+    #   :ends_with
+    #
+    #   :strand # string which include all the tokens in the given exp
+    #   :and
+    #
+    #   :stror # string which include at least one of the tokens
+    #   :or
+    #
+    #   :stroreq # string which is equal to at least one token
+    #
+    #   :strorrx # string which matches the given regex
+    #   :regex
+    #   :matches
+    #
+    #   # numbers...
+    #
+    #   :numeq # equal
+    #   :numequals
+    #   :numgt # greater than
+    #   :gt
+    #   :numge # greater or equal
+    #   :ge
+    #   :gte
+    #   :numlt # greater or equal
+    #   :lt
+    #   :numle # greater or equal
+    #   :le
+    #   :lte
+    #   :numbt # a number between two tokens in the given exp
+    #   :bt
+    #   :between
+    #
+    #   :numoreq # number which is equal to at least one token
+    #
+    def add (colname, operator, val, affirmative=true, no_index=true)
+      op = operator.is_a?(Fixnum) ? operator : OPERATORS[operator]
+      op = op | TDBQCNEGATE unless affirmative
+      op = op | TDBQCNOIDX if no_index
+      lib.tctdbqryaddcond(@query, colname, op, val)
+    end
+    alias :add_condition :add
+
+    #
+    # Sets the max number of records to return for this query.
+    #
+    # (sorry no 'offset' as of now)
+    #
+    def limit (i)
+      lib.tctdbqrysetmax(@query, i)
+    end
+
+    #
+    # Sets the sort order for the result of the query
+    #
+    # The 'direction' may be :
+    #
+    #   :strasc # string ascending
+    #   :strdesc
+    #   :asc # string ascending
+    #   :desc
+    #   :numasc # number ascending
+    #   :numdesc
+    #
+    def order_by (colname, direction=:strasc)
+      lib.tctdbqrysetorder(@query, colname, DIRECTIONS[direction])
+    end
+
+    #
+    # When set to true, only the primary keys of the matching records will
+    # be returned.
+    #
+    def pk_only (on=true)
+      @opts[:pk_only] = on
+    end
+
+    #
+    # When set to true, the :pk (primary key) is not inserted in the record
+    # (hashes) returned
+    #
+    def no_pk (on=true)
+      @opts[:no_pk] = on
+    end
+
+    #
+    # Runs this query (returns a TableResultSet instance)
+    #
+    def run
+      TableResultSet.new(@table, lib.tctdbqrysearch(@query), @opts)
+    end
+
+    #
+    # Frees this data structure
+    #
+    def free
+      lib.tctdbqrydel(@query)
+      @query = nil
+    end
+
+    alias :close :free
+    alias :destroy :free
+  end
+
+  #
+  # The thing queries return
+  #
+  class TableResultSet
+    include CabinetLibMixin
+    include Enumerable
+
+    def initialize (table, list_pointer, query_opts)
+      @table = table
+      @list = list_pointer
+      @opts = query_opts
+    end
+
+    #
+    # Returns the count of element in this result set
+    #
+    def size
+      lib.tclistnum(@list)
+    end
+
+    alias :length :size
+
+    #
+    # The classical each
+    #
+    def each
+      (0..size-1).each do |i|
+        pk = lib.tclistval2(@list, i)
+        if @opts[:pk_only]
+          yield(pk)
+        else
+          val = @table[pk]
+          val[:pk] = pk unless @opts[:no_pk]
+          yield(val)
+        end
+      end
+    end
+
+    #
+    # Returns an array of hashes
+    #
+    def to_a
+      collect { |m| m }
+    end
+
+    #
+    # Frees this query (the underlying Tokyo Cabinet list structure)
+    #
+    def free
+      lib.tclistdel(@list)
+      @list = nil
+    end
+
+    alias :close :free
+    alias :destroy :free
+  end
+end
+