/* Copyright (c) 2009 Sebastian Nowicki * * 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. */ #ifndef SYMBOL_H #define SYMBOL_H /* File: symbol.h A collection of functions and data structures related to symbols and symbol lookup tables. */ /* Enumeration: symbol_type_t An enumeration indicating the type of a symbol. kSymbolTypeString - Indicates a symbol with a string value. kSymbolTypeArray - Indicates a symbol with an array value. kSymbolTypeFunction - Indicates a symbol containing a namespace. See Also: */ typedef enum { kSymbolTypeString, kSymbolTypeArray, kSymbolTypeFunction, } symbol_type_t; /* Type: table_t A symbol table container. */ typedef struct _table_t table_t; /* Type: symbol_t A symbol associating a name with a value. See Also: for possible values. */ typedef struct _symbol_t symbol_t; /* Constructor: symbol_new Initialize and return a new symbol with the given lvalue. The created symbol should be released with . Example: (start code) symbol_t *symbol = symbol_new("foo"); symbol_set_string(symbol, "test"); symbol_release(symbol); (end) Parameters: lvalue - A string representing the name of the symbol. Returns: An initialized symbol with the specified lvalue, or NULL on error. */ symbol_t *symbol_new(char *lvalue); /* Function: symbol_retain Increment the symbol's reference count. This should be used whenever you want to prevent it from being deallocated without your express permission. The symbol is deallocated automatically when its reference count reaches 0. Calling increments the reference count, and calling decrements it. Example: (start code) void use_symbol(symbol_t *symbol) { symbol_retain(symbol); // Do something with symbol symbol_release(symbol); } (end) Parameters: symbol - A reference to the symbol to be retained. Returns: A reference to the symbol. See Also: */ symbol_t *symbol_retain(symbol_t *symbol); /* Function: symbol_release Decrement the symbol's reference count. The symbol is deallocated automatically when its reference count reaches 0. The associated value, if set, will also be deallocated. Parameters: symbol - A reference to the symbol to be released. See Also: */ void symbol_release(symbol_t *symbol); /* Function: symbol_set_string Assign a string value to the symbol. The symbol type is changed to implicitely, to reflect the new value type. Parameters: symbol - A reference to the symbol being modified. rvalue - A string value to be assigned to the symbol. */ void symbol_set_string(symbol_t *symbol, char *rvalue); /* Function: symbol_set_array Assign an array value to the symbol. The symbol type is changed to implicitely, to reflect the new value type. Parameters: symbol - A reference to the symbol being modified. rvalue - An array of strings to be assigned to the symbol. */ void symbol_set_array(symbol_t *symbol, char **rvalue); /* Function: symbol_set_function Assign a namespace to the symbol. The symbol type is changed to implicitely, to reflect the new value type. Parameters: symbol - A reference to the symbol being modified. rvalue - A symbol table to be assigned to the symbol. */ void symbol_set_function(symbol_t *symbol, table_t *table); /* Function: symbol_name Retrieve a string representing the name of the symbol. Parameters: symbol - A reference to the symbol whose name is to be returned. Returns: The name of the symbol. */ char *symbol_name(symbol_t *symbol); /* Function: symbol_type Retrieve a constant indicating the type of the symbol. Parameters: symbol - A reference to the symbol whose name is to be returned. Returns: A constant indicating the type of the symbol. See Also: */ symbol_type_t symbol_type(symbol_t *symbol); /* Function: symbol_string Retrieve the string value associated with the symbol. If the symbol does not hold a string value, NULL is returned. Parameters: symbol - The symbol to retrieve the value from. Returns: The string value associated with the symbol. */ char *symbol_string(symbol_t *symbol); /* Function: symbol_array Retrieve the array value associated with the symbol. If the symbol does not hold an array value, NULL is returned. Parameters: symbol - The symbol to retrieve the value from. Returns: The array value associated with the symbol. */ char **symbol_array(symbol_t *symbol); /* Function: symbol_function Retrieve the namespace value associated with the symbol. If the symbol does not hold a namespace value, NULL is returned. Parameters: symbol - The symbol to retrieve the value from. Returns: The namespace value associated with the symbol. */ table_t *symbol_function(symbol_t *symbol); /* Constructor: table_new Initialize and return a new table. The created table should be released with . Returns: An initialized table, or NULL on error. See Also: */ table_t *table_new(); /* Constructor: table_new_with_parent Initialize and return a new table with the specified table as the parent. This is the designated constructor. The created table should be released with . Parameters: parent - A parent table. This is used when searching recursively. Returns: An initialized table, or NULL on error. See Also: , */ table_t *table_new_with_parent(table_t *parent); /* Function: table_retain Increment the tables's reference count. This should be used whenever you want to prevent it from being deallocated without your express permission. The table is deallocated automatically when its reference count reaches 0. Calling increments the reference count, and calling decrements it. Example: (start code) void use_table(table_t *table) { table_retain(table); // Do something with table table_release(table); } (end) Parameters: table - A reference to the table to be retained. Returns: A reference to the table. See Also: */ table_t *table_retain(table_t *table); /* Function: table_release Decrement the table's reference count. The table is deallocated automatically when its reference count reaches 0. Any contained symbols will also be deallocated. Parameters: table - A reference to the table to be released. See Also: */ void table_release(table_t *table); /* Function: table_lookup Search for a symbol with the name lvalue. If the symbol is not found, parent namespaces are not searched, and NULL is returned. Parameters: table - A reference to the table being searched. lvalue - A string representing the name of the symbol to be found. Returns: A symbol whose name is lvalue, or NULL if such a symbol is not found. */ symbol_t *table_lookup(table_t *table, char *lvalue); /* Function: table_lookupr Search recusively for a symbol with the name lvalue. If the symbol is not found in the current namespace, the parent namespace is searched, until there are no parent namespaces. If the symbol is not found at this point, NULL is returned. Example: (start code) char *value = NULL; symbol_t *symbol = symbol_new("foo"); table_t *table = table_new_with_parent(parent); symbol_set_string(symbol, "bar"); table_insert(parent, symbol); symbol_string(table_lookupr(table, "foo")); // "bar" table_release(symbol); table_release(table); table_release(parent); (end) Parameters: table - A reference to the table being searched. lvalue - A string representing the name of the symbol to be found. Returns: A symbol whose name is lvalue, or NULL if such a symbol is not found. */ symbol_t *table_lookupr(table_t *table, char *lvalue); /* Function: table_insert Insert a symbol into the table. The symbol will be retained until it is either removed with , or the table is deallocated with . Parameters: table - A reference to the table being modified. symbol - The symbol to be inserted. Returns: True (1) on success or false (0) on error. */ int table_insert(table_t *table, symbol_t *symbol); /* Function: table_remove Remove a symbol from the table. Parameters: table - A reference to the table being modified. lvalue - A string representing the name of the symbol. Returns: True (1) on success or false (0) on error. */ int table_remove(table_t *table, char *lvalue); /* Function: table_parent Retrieve the parent namespace of the table. Parameters: table - A reference to the table to retrieve the parent from. Returns: The parent namespace of table. */ table_t *table_parent(table_t *table); #endif