Class: KirbyBase

Inherits:
Object
  • Object
show all
Includes:
DRb::DRbUndumped
Defined in:
lib/og/store/kirby/kirbybase.rb

Overview

KirbyBase is a class that allows you to create and manipulate simple, plain-text databases. You can use it in either a single-user or client-server mode. You can select records for retrieval/updating using code blocks.

Author

Jamey Cribbs ([email protected])

Homepage

www.netpromi.com/kirbybase.html

Copyright

Copyright © 2005 NetPro Technologies, LLC

License

Distributes under the same terms as Ruby

History:

2005-03-28

Version 2.0

  • This is a completely new version. The interface has changed dramatically.

2005-04-11

Version 2.1

  • Changed the interface to KirbyBase#new and KirbyBase#create_table. You now specify arguments via a code block or as part of the argument list.

  • Added the ability to specify a class at table creation time.

    Thereafter, whenever you do a #select, the result set will be an array of instances of that class, instead of instances of Struct. You can also use instances of this class as the argument to KBTable#insert, KBTable#update, and KBTable#set.

  • Added the ability to encrypt a table so that it is no longer stored as a plain-text file.

  • Added the ability to explicity specify that you want a result set to be sorted in ascending order.

  • Added the ability to import a csv file into an existing table.

  • Added the ability to select a record as if the table were a Hash with it’s key being the recno field.

  • Added the ability to update a record as if the table were a Hash with it’s key being the recno field.

2005-05-02

Version 2.2

  • By far the biggest change in this version is that I have completely redesigned the internal structure of the database code. Because the KirbyBase and KBTable classes were too tightly coupled, I have created a KBEngine class and moved all low-level I/O logic and locking logic to this class. This allowed me to restructure the KirbyBase class to remove all of the methods that should have been private, but couldn’t be because of the coupling to KBTable. In addition, it has allowed me to take all of the low-level code that should not have been in the KBTable class and put it where it belongs, as part of the underlying engine. I feel that the design of KirbyBase is much cleaner now. No changes were made to the class interfaces, so you should not have to change any of your code.

  • Changed str_to_date and str_to_datetime to use Date#parse method.

  • Changed #pack method so that it no longer reads the whole file into memory while packing it.

  • Changed code so that special character sequences like &linefeed; can be part of input data and KirbyBase will not interpret it as special characters.

KirbyBase

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(connect_type = :local, host = nil, port = nil, path = './', ext = '.tbl') {|_self| ... } ⇒ KirbyBase

initialize

++ Create a new database instance.

connect_type

Symbol (:local, :client, :server) specifying role to play.

host

String containing IP address or DNS name of server hosting database. (Only valid if connect_type is :client.)

port

Integer specifying port database server is listening on. (Only valid if connect_type is :client.)

path

String specifying path to location of database tables.

ext

String specifying extension of table files.

Yields:

  • (_self)

Yield Parameters:

  • _self (KirbyBase) —

    the object that the method was called on

Raises:

  • (ArgumentError) 


81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/og/store/kirby/kirbybase.rb', line 81

def initialize(connect_type=:local, host=nil, port=nil, path='./',
 ext='.tbl')
    @connect_type = connect_type
    @host = host
    @port = port
    @path = path
    @ext = ext
    
    # See if user specified any method arguments via a code block.
    yield self if block_given?
    
    # After the yield, make sure the user doesn't change any of these
    # instance variables.
    class << self
        private :connect_type=, :host=, :path=, :ext=
    end    

    # Did user supply full and correct arguments to method?
    raise ArgumentError, 'Invalid connection type specified' unless (
     [:local, :client, :server].include?(@connect_type))
    raise "Must specify hostname or IP address!" if \
     @connect_type == :client and @host.nil?
    raise "Must specify port number!" if @connect_type == :client and \
     @port.nil?
    raise "Invalid path!" if @path.nil?
    raise "Invalid extension!" if @ext.nil?
    
    # If running as a client, start druby and connect to server.
    if client?
        DRb.start_service()
        @server = DRbObject.new(nil, 'druby://%s:%d' % [@host, @port])
        @engine = @server.engine
        @path = @server.path
        @ext = @server.ext
    else
        @engine = KBEngine.create_called_from_database_instance(self)    
    end
end

Instance Attribute Details

#connect_type ⇒ Object

Returns the value of attribute connect_type.



64
65
66
 
# File 'lib/og/store/kirby/kirbybase.rb', line 64

def connect_type
  @connect_type
end

#engine ⇒ Object (readonly)

Returns the value of attribute engine.



62
63
64
 
# File 'lib/og/store/kirby/kirbybase.rb', line 62

def engine
  @engine
end

#ext ⇒ Object

Returns the value of attribute ext.



64
65
66
 
# File 'lib/og/store/kirby/kirbybase.rb', line 64

def ext
  @ext
end

#host ⇒ Object

Returns the value of attribute host.



64
65
66
 
# File 'lib/og/store/kirby/kirbybase.rb', line 64

def host
  @host
end

#path ⇒ Object

Returns the value of attribute path.



64
65
66
 
# File 'lib/og/store/kirby/kirbybase.rb', line 64

def path
  @path
end

#port ⇒ Object

Returns the value of attribute port.



64
65
66
 
# File 'lib/og/store/kirby/kirbybase.rb', line 64

def port
  @port
end

Instance Method Details

#client? ⇒ Boolean

client?

++ Is this running as a client?

Returns:

  • (Boolean) 


136
137
138
 
# File 'lib/og/store/kirby/kirbybase.rb', line 136

def client?
    @connect_type == :client
end

#create_table(name = nil, *field_defs) {|t| ... } ⇒ Object

create_table

++ Create new table and return a reference to the new table.

name

Symbol or string of table name.

field_defs

List of field names (Symbols) and field types (Symbols)

Block

Optional code block allowing you to set the following:

encrypt

true/false specifying whether table should be encrypted.

record_class

Class or String specifying the user create class that will be associated with table records.

Yields:

  • (t) 


187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/og/store/kirby/kirbybase.rb', line 187

def create_table(name=nil, *field_defs)
    raise "Can't call #create_table from server!" if server?

    t_struct = Struct.new(:name, :field_defs, :encrypt, :record_class)
    t = t_struct.new
    t.name = name
    t.field_defs = field_defs
    t.encrypt = false
    t.record_class = 'Struct'
    
    yield t if block_given?
    
    raise "No table name specified!" if t.name.nil?
    raise "No table field definitions specified!" if t.field_defs.nil?

    @engine.new_table(t.name, t.field_defs, t.encrypt, 
     t.record_class.to_s)
    return get_table(t.name)
end

#drop_table(tablename) ⇒ Object

drop_table

++ Delete a table.

tablename

Symbol or string of table name.



215
216
217
 
# File 'lib/og/store/kirby/kirbybase.rb', line 215

def drop_table(tablename)
    return @engine.delete_table(tablename)
end

#get_table(name) ⇒ Object

get_table

++ Return a reference to the requested table.

name

Symbol or string of table name.



167
168
169
170
171
172
173
 
# File 'lib/og/store/kirby/kirbybase.rb', line 167

def get_table(name)
    raise('Do not call this method from a server instance!') if server?
    raise('Table not found!') unless table_exists?(name)
    
    return KBTable.create_called_from_database_instance(self, 
     name.to_sym, File.join(@path, name.to_s + @ext))
end

#local? ⇒ Boolean

local?

++ Is this running in single-user, embedded mode?

Returns:

  • (Boolean) 


146
147
148
 
# File 'lib/og/store/kirby/kirbybase.rb', line 146

def local?
    @connect_type == :local
end

#server? ⇒ Boolean

server?

++ Is this running as a server?

Returns:

  • (Boolean) 


126
127
128
 
# File 'lib/og/store/kirby/kirbybase.rb', line 126

def server?
    @connect_type == :server
end

#table_exists?(tablename) ⇒ Boolean

table_exists?

++ Return true if table exists.

tablename

Symbol or string of table name.

Returns:

  • (Boolean) 


227
228
229
 
# File 'lib/og/store/kirby/kirbybase.rb', line 227

def table_exists?(tablename)
    return @engine.table_exists?(tablename)
end

#tables ⇒ Object

tables

++ Return an array containing the names of all tables in this database.



156
157
158
 
# File 'lib/og/store/kirby/kirbybase.rb', line 156

def tables
    return @engine.tables
end