Script Index


/var/lib/sorcery/modules/libhash

Set of functions for working with an associative array type data structure. Values can be stored and retrieved using strings as the index into the data structure instead of numbers. The hash data structure provided in this file allows you to store values into fields of a table. The 'hash_put' function takes the name of the table, a field name in the table, and the value to be stored in the table. The 'hash_get' function retrieves a value from the table given the table and field name.

To store a value into a field of a table, use hash_put:
hash_put "myTable" "aField" "theValue"
The value stored in the table can be retrieved with hash_get:
hash_get "myTable" "aField"
In this example, the hash_get function would echo "theValue".
hash_get_ref can also be used here and has the benefit of being forkless.

IMPLEMENTATION NOTE


Bash does not provide direct support for hash tables. These functions are implemented by first building a variable using the table name and field name, then using the eval function to store (retrieve) value into (from) the variable.
The idea for the hash data structure in bash was inspired by a short example by Phil Howard which shows the use of hashes in bash. Phil Howard's original example can be found here: http://www.codebits.com/bit.cfm?BitID=92


function hash_build_variable_name()

Parameters:

Type

Private

Description

Given a table and field name, bulds the name of the variable into which a value will be stored. Also changes '+', '-', and '.' in the table name into text since bash doesn't like variable names with those characters.


function hash_unbuild_field_name()

Parameters:

Type

Private

Description

most likely reverses hash_build_field_name


function hash_put()

Parameters:

Description

Saves the value in the specified table/field.


function hash_get()

Parameters:

Stdout

Value stored in table/field

Description

Echos the value stored in the table/field. If no value was previously stored in the table/field, this function echos an empty string.


function hash_get_ref()

Parameters:

Stdout

none

Description

Returns the value stored in the table/field through the upvar variable name. If no value was previously stored in the table/field, then an empty string is returned.


function hash_append()

Parameters:

Description

Appends the value to the specified table/field.


function hash_export()

Parameters:

Description

'export' all the values in the table. This is useful for getting hash table data from cast's pass_one/two into pass_three/pass_four which are run through make. Essentially exporting lets us pass the variables through make.


function hash_unset()

Parameters:

Description

Unsets field. Deletes value.


function hash_unset_part()

Parameters:

Description

The reverse of hash_append, it removes an item from the field's value.


function hash_reset()

Parameters:

Description

Unsets all fields in a table.


function hash_get_table()

Parameters:

Stdout

table data

Description

Outputs the entire table data, with fields separated by the optional delimiter. If no delimiter is give, n will be used.


function hash_get_table_fields()

Parameters:

Stdout

Fields in table

Description

Outputs all of the fields in the table , with fields separated by the optional delimiter. If no delimiter is give, n wil be used.


function hash_debug_dump()

Parameters:

Stdout

Print the table in some reasonably readable form

Description

As the name would imply, this is mainly for development use and is not intended for regular use.