a_column

The A_Column class is defined in a_table.rb. This class is co-located with the A_Table_Data class in the a_column.rb module. The most useful aspect of columns is the ability to easily perform checks on the data before it is inserted into tables. These checks are also called column constraints. There are three kinds of column constraints:

Not null checking:

When this flag in the column is not nil, the every insert and and update is checked to make sure this column is not nil. A not null column constraint error is raised if this column is nil.

Constraint checking:

You can assign a Ruby expression to any column that is automatically executed (using eval) before every update and insert. If result of this expression is not nil, then a constraint violation error is raised. Column constraints are limited to checking for 4 values or 4 checks per column. Additionally, this checking can't look at other columns nor look in other tables. If you need more values or the result of this column is dependant on another column or table, then use a trigger as defined in A_Table. See the constraint() and constraint=() methods below for more details.

Type checking:

If you provide a type for the column, then this type is used to perform certain other column constraints on the column during inserts and updates. For example, if the data type is integer, the every value is checked to make sure it is number and it is in the range of an integer. Ruby makes it very easy to stuff any kind of value into any kind of column. This allows you control, in degree, what the data looks like. See the type() and type=() methods below for more details.

If the above column constraints don't adequately meet your needs in controlling the data that is stuffed into this column, then use a trigger as defined in the A_Table class. Another useful aspect of columns is that they allow you to easily perform an action every time this column is inserted or updated into a table. For example, if you always want the name in your table capitalized, you can add an action like '%s.capatilize'. This means that you don't need to police every insert and update to make sure the name is capitalized because ArunaDB will automatically do it for via a column action.

The following error was added for this class:

ColumnConstraintError - this is raised when the value of a column violates one ore more of the column constraints.

Dependencies:

a_debug.rb - this provides debugging messages for all of my Ruby code. See a_debug.html for more details.

Limitations:

Column constraints are limited to checking for 4 values or 4 checks per column. Additionally, this checking can't look at other columns nor look in other tables. If you need more values or the result of this column is dependant on another column or table, then use a trigger as defined in A_Table.
Column actions are limited to one action for each column. If you need to perform a complex action for this column or the result of this column is dependant on another column or table then use a trigger as defined in A_Table.

Performance Considerations:

Use a valid apack type for the type of the column when possible. If every column uses a valid apack type, optimizations are performed on the data helping everything to run faster.

To Do:

None

Usage:

See A_Table.

Class Methods:

A_Column.new(name, type=nil, not_null=nil, default=nil, col_constraint=nil, col_action=nil, default_display=nil)

Create a new column. Creating an A_Table requires and array of A_Column.

name - the name of this column. This automatically name is forced to lower case because a_conform is called.
type - this is an apack type. If the data type of this column does not fit nicely into one of the apack types, then leave this as nil and Marshal.dump/load will be used. See the type() and type=() methods below for more details. The type is used for packing data in the table. If all columns in the table have a valid type, then the data in the table is packed as it is stored in the btree (the A_Table class uses the A_BTree class for data storage and the A_BTree class uses the A_Buffer class for storage). The A_Buffer class actually does the packing as rows are stored in the btree. If one column does have a valid type, then Marshal.dump is used to store the data.
not_null - when true this column should never contain nil. An error is raised whenever you update or insert and attempt to set this column to nil. See the not_nil() and not_nil=() methods below for more details. Set to true to enable not null constraint checking.
default - this is the default valued used during inserted and this column is not provided during the insert. See the default() and default=() methods below for more details.
col_constraint - this allows you to construct a Ruby statement that is evaluated during each insert and udpate to make sure this column is being set properly. See the constraint() and constraint=() methods below for more details. Nil means that this form of column constraint is disabled.
col_action - this allows you to construct a Ruby statement that is evaluated during each insert and update to make sure the data is consistent. This will actually transform the data to suit your needs just before this column is insert into or updated in a table. Nil will disable this feature. See the action() and action=() methods below for more details.
default_display - this is a format string that is used when printing the contents of a table. This allows you to format the data that is printed. See the display() and display=() methods below for more details.

Instance Methods:

action()

Returns the @action setting for this column. This will be nil if there are no column actions for this column. A column action is a Ruby expression that is evaluated, using eval(), whenever this column is inserted or updated. For example:

return eval sprintf(@action, value) # supports things like %s.capitalize!

This allows you to alter the value of the column right before the insert or update. This is valuable for keeping your data consistant without have to create a trigger. It is very useful for Ruby command like capatilize, upcase, downcase, and/or trim.

action=(action_command)

Sets the @action setting for this column to action_command. Set to nil to remove any column actions. A column action is a Ruby expression that is evaluated, using eval(), whenever this column is inserted or updated. For example:

return eval sprintf(@action, value) # supports things like %s.capitalize!

"'%s'.capitalize" - capitalize this string

"'%s'.downcase" - force this string to lowercase

"'%s'.strip" - eliminate leading and trailing white space

constraint()

Returns the @constraint setting for this column. This will be nil if there are no column constraints for this column. This is a Ruby expression that is evaluated, using eval(), whenever this column is inserted or updated. For example:

rc = eval sprintf(@constraint, value, value, value, value)

The resulting eval() should return true or nil. If the resulting eval() returns true, then a constraint violation error is raised.

constraint=(constraint_command)

Sets the @constraint setting for this column to constraint_command. Set this to nil to remove this form of column constraint checking for this column. This is a Ruby expression that is evaluated, using eval(), whenever this column is inserted or updated. For example:

rc = eval sprintf(@constraint, value, value, value, value)

The resulting eval() should return true or nil. If the resulting eval() returns true, then a constraint violation error is raised. Column constraints are limited to checking for 4 values or 4 checks per column. Additionally, this checking can't look at other columns nor look in other tables. If you need to check for more than 4 values or the result of this column is dependent on another column or table, then use a trigger as defined in A_Table. Here are some common examples:

'%d > 0' - makes sure this numeric column is > 0

"'%s' != ''" - makes sure this string column is not an empty string

"'%s' == 'M' || '%s' == 'F'" - makes sure this char column is either 'M' or 'F'

"'%s' == 'Y' || '%s' == 'N'" - makes sure this char column is either 'Y' or 'N'

'%d == 0 || %d == 1' - makes sure this numeric column is either 0 or 1

'%d == 1 || %d == 2 || %d == 4 || %d == 8 || %d == 16' - makes sure this numeric column is either 1, 2, 4, or 8. The %d (or %s or any sprintf format variable) can be used a max of 4 times. This would likely fail depending on what sprintf does with a %d and no matching parameter.

curr_val(sequence_name)

This is a short cut for A_Sequences.curr_val. This returns the current value of the sequence.

default()

Returns the @default value for this column. This is only used during an A_Table.insert() and this column is nil.

default=(value)

Sets the @default value for this column to value. If this column has a nil value during an insert, then the default value is inserted. This is column attribute used during an update. Examples:

"next_val('member_seq')" - sets the column value to the next value in the sequence

"Time.now" - sets the column value to the current time

deleted()

Returns true if this column is scheduled for deletion. Columns are not physically deleted from tables until the table is exported and imported.

display()

Returns the current display value for this column.

display=(value)

Sets the current display value for this column. This is used when printing column values. If this value is not nil then the column is printed using (@display % t__value). This will format the value for this column as it is printed. This allows you to set up how you want this column to print by default.

length()

Returns the length of the column in bytes or characters if and on if the length can be determined.

name()

Returns the @name of this column.

next_val(sequence_name)

This is a short cut for A_Sequences.next_val. This allows you to easily set up auto incramenting numbers. This incraments the curr_val of the sequence (the current value) and then return the newly incramented value.

not_null()

Returns the @not_null setting for this column. Should be nil or true. If not_null != nil, then this column can never be nil. This is a special form of a column constraint.

not_null=(value)

Sets the @not_null setting for this column to value. Should be nil or true. If not_null != nil, then this column can never be nil. This is a special form of a column constraint. If this is true, then a constraint violation error will get raised whenever you attempt an insert or update and this column has a nil value. Set to true to enable not null constraint checking.

to_s()

Returns a string containing the various settings for this column.

type()

Returns the @type of this column.

type=(value)

This method is not supported yet. Sets the @type of this column to value. Value must be nil or a valid apack type. If the data type of this column does not fit nicely into one of the apack types, then set this to nil and Marshal.dump/load will be used. If you change the column type of an existing table, you must export and import for the change to take effect. Otherwise the column constraint checking many not match the new type of the column.

type_name()

Returns a name (string) describing the type of this column if and only if a valid type has been provided for this column.

Testing:

See A_Table.

A_Debug Usage:

19 - prints all column constraint checking and column actions