Package clearsilver

Fast and powerful HTML templating system

http://www.clearsilver.net/

ClearSilver is a fast, powerful, and language-neutral HTML template
system. In both static content sites and dynamic HTML applications,
it provides a separation between presentation code and application
logic which makes working with your project easier. The design of
ClearSilver began in 1999, and evolved during its use at onelist.com,
egroups.com, and Yahoo! Groups. Today many other projects and
websites are using it.

Library Functions (Section 3)
cBroadcast
Broadcasts a signal to all threads waiting on condition variable <cond>. MT-Level: Safe.
cCreate
Initializes the condition variable <cond>. MT-Level: Safe for unique <cond>.
cDestroy
Destroys the condition variable <cond> that was initialized by cCreate(). MT-Level: Safe for unique <cond>.
cgi_cookie_authority
cgi_cookie_authority will walk the CookieAuthority portion of the CGI HDF data set, and return the matching domain if it exists. The purpose of this is so that...
cgi_cookie_clear
cgi_cookie_clear will send back a Set-Cookie string that will attempt to stop a browser from continuing to send back a cookie. Note that the cookie has to match...
cgi_cookie_set
cgi_cookie_set will issue a Set-Cookie header that should cause a browser to return a cookie when required. Note this function does no escaping of anything, you...
cgi_cs_init
cgi_cs_init initializes a CS parser with the CGI HDF context, and registers the standard CGI filters
cgi_debug_init
cgi_debug_init initializes a CGI program for standalone debugging. By running a ClearSilver CGI program with a filename on the command line as the first...
cgi_destroy
cgi_destroy will destroy all the data associated with a CGI, which mostly means the associated HDF and removal of any files that were uploaded via...
cgi_display
cgi_display will render the CS template pointed to by cs_file using the CGI's HDF data set, and send the output to the user. Note that the output is actually...
cgi_error
cgi_error will output a 500 error containing the specified error message. This function is likely to be removed from future versions in favor of a user error...
cgi_filehandle
cgi_filehandle will return the stdio FILE pointer associated with a file that was uploaded using multipart/form-data. The FILE pointer is positioned at the...
cgi_init
cgi_init initializes the ClearSilver CGI environment, including creating the HDF data set. It will then import the standard CGI environment variables into that...
cgi_neo_error
cgi_neo_error will output a 500 error containing the NEOERR call backtrace. This function is likely to be removed from future versions in favor of some sort of...
cgi_output
Normally, this is called by cgi_display, but some people wanted it external so they could call it directly.
cgi_parse
We split cgi_init into two sections, one that parses just the basics, and the second is cgi_parse. cgi_parse is responsible for parsing the entity body of the...
cgi_redirect
cgi_redirect will redirect the user to another page on your site. This version takes only the path portion of the URL. As with all printf style commands, you...
cgi_redirect_uri
cgi_redirect_uri will redirect the user to another page on your site. This version takes the full URL, including protocol/domain/port/path. As with all printf...
cgi_register_parse_cb
The ClearSilver CGI Kit has built-in functionality to handle the following methods: GET -> doesn't have any data except query string, which is processed for all...
cgi_url_escape
cgi_url_escape will do URL escaping on the passed in string, and return a newly allocated string that is escaped. Characters which are escaped include control...
cgi_url_escape_more
cgi_url_escape_more will do URL escaping on the passed in string, and return a newly allocated string that is escaped. Characters which are escaped include...
cgi_url_unescape
cgi_url_unescape will do URL unescaping on the passed in string. This function modifies the string in place This function will decode any %XX character, and...
cgi_url_validate
cgi_url_validate will check that a URL starts with one of the accepted safe schemes. If not, it returns "#" as a safe substitute. Currently accepted schemes are...
cgi_vredirect
cgi_vredirect is mostly used internally, but can be used if you need a varargs version of the function.
cgiwrap_getenv
cgiwrap_getenv wraps the getenv function for access to environment variables, which are used to pass data to CGI scripts. This version differs from the system...
cgiwrap_init_emu
cgiwrap_init_emu sets up the cgiwrap subsystem for use in an emulated environment where you are providing routines to use in place of the standard routines, ie...
cgiwrap_init_std
cgiwrap_init_std will initialize the cgiwrap subsystem to use the default CGI functions, ie getenv/putenv/stdio. In reality, all this is doing is setting up the...
cgiwrap_iterenv
cgiwrap_iterenv allows a program to iterate over all the environment variables. This is probably mostly used by the default debug output.
cgiwrap_putenv
cgiwrap_putenv wraps the putenv call. This is mostly used by the cgi_debug_init function to create an artificial environment. This version differs from the...
cgiwrap_read
cgiwrap_read is used to read incoming data from the client, usually from a POST or PUT HTTP request. It wraps the part of fread(stdin).
cgiwrap_write
cgiwrap_write is the block data output function for cgiwrap that replaces fwrite(stdout) in regular CGIs
cgiwrap_writef
cgiwrap_writef is the formatted output command that replaces printf or fprintf(stdout) in a standard CGI
cgiwrap_writevf
cgiwrap_writevf is the formatted output command that replaces vprintf or fvprintf(stdout) in a standard CGI It is also used by cgiwrap_writef (the actual...
cs_destroy
cs_destroy will clean up all the memory associated with a CSPARSE structure, including strings passed to cs_parse_string. This does not clean up any memory...
cs_dump
cs_dump will dump the CS parse tree in the parse struct. This can be useful for debugging your templates. This function also uses the CSOUTFUNC callback to...
cSignal
Sends a signal to one thread waiting on condition variable <cond>. MT-Level: Safe.
cs_init
cs_init will create a CSPARSE structure and initialize it. This structure maintains the state and information necessary for parsing and rendering a CS template...
cs_parse_file
cs_parse_file will parse the CS template located at path. It will use hdf_search_path() if path does not begin with a '/'. The parsed CS template will be...
cs_parse_string
cs_parse_string parses a string. The string is modified, and internal references are kept by the parse tree. For this reason, ownership of the string is...
cs_register_esc_strfunc
cs_register_esc_strfunc functions exactly as cs_register_strfunc except that it changes the evaluation escaping context to disable default escaping.
cs_register_fileload
cs_register_fileload registers a fileload function that overrides the built-in function. The built-in function uses hdf_search_path and ne_file_load (based on...
cs_register_strfunc
cs_register_strfunc will register a string function that can be called during CS render. This not-callback is designed to allow for string formating/escaping...
cs_render
cs_render will evaluate a CS parse tree, calling the CSOUTFUNC passed to it for output. Note that calling cs_render multiple times on the same parse tree may or...
cWait
Waits for a signal on condition variable <cond>. The mutex <mutex> must be locked by the thread. MT-Level: Safe.
dictCleanup
Calls <cleanup> for every item in <dict>. If <cleanup> returns true, then item is removed from <dict>. MT-Level: Safe if <dict> thread-safe.
dictCreate
Returns a dictionary. If <threaded> is true, list is multi-thread safe. <root>, <maxLevel>, and <flushLimit> act as for skipNewList() (see skiplist.h) MT-Level...
dictDestroy
Release all resources used by <dict>. MT-Level: Safe for unique <dict>.
dictModifyValue
Finds <id>'s value and calls <update>. If <id> is not in <dict>, calls <new> to obtain a new value. MT-Level: Safe if <dict> thread-safe.
dictNext
Can be used to iterate through values in the dictionary. The order is the order of the hash of the ids, which isn't usefully externally. Will return the value...
dictReleaseLock
Releases the lock on the value associated with <lock>. Once the lock is released, the dictCleanupFunc callback can be called for the value (see dictCleanup())...
dictRemove
Removes item identified by <id> from <dict>. MT-Level: Safe if <dict> thread-safe.
dictSearch
Searches for <id> in <dict>, and returns value if found, or NULL if not. If <plock> is non-NULL, then the lock returned in <plock> will be associated with the...
dictSetValue
Updates the <id>/<value> pair into <dict>. If <id> is not in <dict>, it is created. MT-Level: Safe if <dict> thread-safe.
fCreate
Creates a file lock on named file <file>. The lock is returned in <plock>. MT-Level: Safe.
fDestroy
Destroys the lock <lock> that was created by fCreate() or fFind(). MT-Level: Safe for unique <lock>.
fFind
Find a file identified by the path <file>, and returns a lock identifier for it in <plock>. If the file doesn't exist, returns true. MT-Level: Safe.
filter_create_fd
filter_create_fd and filter_create_fp are what popen been: a mechanism to create sub processes and have pipes to all their input/output. The concept was taken...
filter_create_fp
filter_create_fp is identical to filter_create_fd, except each of the pipes is wrapped in a buffered stdio FILE
filter_wait
filter_wait wraps the waitpid call and raises an error (with description) if the call failed. Note that if the ask for the exitcode and the process exited with...
fLock
Acquires the lock identified by <lock>. This call blocks until the lock is acquired. MT-Level: Safe.
fUnlock
Releases the lock identified by <lock>. MT-Level: Safe.
hdf_copy
hdf_copy is a deep copy of an HDF tree pointed to by src to the named node of dest. dest and src need not be part of the same data set
hdf_destroy
hdf_destroy is used to deallocate all memory associated with an hdf data set. Although you can pass an HDF node as an argument to this function, you are likely...
hdf_dump
dump an HDF dataset to stdout Description: Input: Output: Returns:
hdf_dump_format
dump an HDF dataset to FILE *fp Description: Input: Output: Returns:
hdf_dump_str
dump an HDF dataset to STRING Description: Input: Output: Returns:
hdf_get_attr
Description: Input: Output: Returns:
hdf_get_child
hdf_get_child will walk the dataset starting at hdf to name, and return the first child of that node
hdf_get_copy
hdf_get_copy is similar to hdf_get_value, except that it returns an malloc'd copy of the string.
hdf_get_int_value
hdf_get_int_value walks the HDF data set pointed to by hdf to name, and returns the value of that node converted to an integer. If that node does not exist, or...
hdf_get_node
hdf_get_node is similar to hdf_get_obj, except instead of stopping if it can't find a node in the tree, it will create all of the nodes necessary to hand you...
hdf_get_obj
hdf_get_obj walks the dataset given by hdf to the node named name, and then returns the pointer to that node
hdf_get_value
hdf_get_value walks the data set pointed to by hdf via name and returns the string value located there, or defval if the node doesn't exist
hdf_get_valuef
hdf_get_valuef walks the data set pointed to by hdf via namefmt printf expanded with varargs, and returns the string value located there, or NULL if it doesn't...
hdf_get_valuevf
hdf_get_valuevf walks the data set pointed to by hdf via namefmt printf expanded with varargs ap, and returns the string value located there, or NULL if it...
hdf_init
hdf_init initializes an HDF data set and returns the pointer to the top node in the data set.
hdf_obj_attr
Return the HDF Attributes for a node Description: Input: Output: Returns:
hdf_obj_child
hdf_obj_child and the other hdf_obj_ functions are accessors to the HDF dataset. Although we do not currently "hide" the HDF struct implementation, we recommend...
hdf_obj_name
hdf_obj_name is an accessor function for a datset node which returns the name of the node. This is just the local name, and not the full path.
hdf_obj_next
hdf_obj_next is an accessor function for the HDF struct
hdf_obj_top
hdf_obj_top is an accessor function which returns a pointer to the top of the dataset, the node which was returned by hdf_init. This is most useful for...
hdf_obj_value
hdf_obj_value is an accessor function for a dataset node which returns the value of the node, or NULL if the node has no value. This is not a copy of the value...
hdf_read_string
read an HDF string Description: Input: Output:
hdf_read_string_ignore
Read an HDF string and ignore errors Description: Input: Output:
hdf_register_fileload
hdf_register_fileload registers a fileload function that overrides the built-in function. The built-in function uses hdf_search_path and ne_file_load (based on...
hdf_remove_tree
delete a subtree of an HDF dataset Description: Input: Output: Returns:
hdf_search_path
hdf_search_path is a convenience/utility function that searches for relative filenames in a search path. The search path is the list given by the children of...
hdf_set_attr
Description: Input: Output: Returns:
hdf_set_buf
hdf_set_buf is similar to hdf_set_value, except the dataset takes ownership of the value instead of making a copy of it. The dataset assumes that value was...
hdf_set_copy
hdf_set_copy first walks the hdf dataset to the named src node, and then copies that value to the named dest node. If the src node is not found, an error is...
hdf_set_int_value
hdf_set_int_value is a helper function that maps an integer to a string, and then calls hdf_set_value with that string
hdf_set_symlink
hdf_set_symlink creates a link between two sections of an HDF dataset. The link is "by name" hence the term "symlink". This means that the destination node does...
hdf_set_value
hdf_set_value will set the value of a named node. All of the interstitial nodes which don't exist will be created with a value of NULL. Existing nodes are not...
hdf_set_valuef
hdf_set_valuef is a convenience function that wraps hdf_set_value. Due to limitations of C, the fmt is in the format "name=value", where we will first format...
hdf_sort_obj
hdf_sort_obj will sort the children of an HDF node, based on the given comparison function. This function works by creating an array of the pointers for each...
hdf_write_file
write an HDF data file Description: Input: Output:
hdf_write_file_atomic
write an HDF data file atomically
hdf_write_string
serialize an HDF dataset to a string Description: Input: Output:
mCreate
Initializes the mutex <mutex>. MT-Level: Safe for unique <mutex>.
mDestroy
Destroys the mutex <mutex> that was initialized by mCreate(). MT-Level: Safe for unique <mutex>.
mLock
Locks the mutex <mutex>. This call blocks until the mutex is acquired. MT-Level: Safe.
mUnlock
Unlocks the mutex <mutex>. MT-Level: Safe.
nerr_error_string
returns the string associated with an error (the bottom level of the error chain)
nerr_error_traceback
returns the full traceback of the error chain
nerr_handle
nerr_handle is a convenience function. It is the equivalent of nerr_match, but it will also deallocate the error chain on a match.
nerr_ignore
you should only call this if you actually handle the error (should I rename it?). Free's the error chain.
nerr_init
initialize the NEOERR system. Can be called more than once. Is not thread safe. This registers all of the built in error types as defined at the top of this...
nerr_log_error
currently, this prints out the error to stderr, and free's the error chain
nerr_match
nerr_match is used to walk the NEOERR chain and match the error against a specific error type. In exception parlance, this would be the equivalent of "catch"...
nerr_pass
this function is used to pass an error up a level in the call chain (ie, if the error isn't handled at the current level). This allows us to track the traceback...
nerr_pass_ctx
this function is used to pass an error up a level in the call chain (ie, if the error isn't handled at the current level). This allows us to track the traceback...
nerr_register
register an error type. This will assign a numeric value to the type, and keep track of the "pretty name" for it.
skipDelete
Delete the item associated with <key> from <list>. MT-Level: Safe if <list> thread-safe.
skipFreeList
Release all resources used by <list> including all key/value pairs. MT-Level: Safe for unique <list>.
skipInsert
Inserts the <key>/<value> pair into the <list>. Key values 0 and -1 are reserved (and illegal). If key is already in list, and <allowUpdate> is true, value is...
skipNewList
Returns a new skip list. If <threaded> is true, list is multi-thread safe. <root> and <maxLevel> determine performance and expected size (see discussion above)...
skipNext
Searches in list <list> for item with key next larger that the one in <pkey>, and returns its value if found, or NULL if not. If <plock> is non-NULL, then the...
skipRelease
Releases the lock on the value associated with <lock>. Once the lock is released, the freeValue callback can be called and the item freed (see skipNewList())...
skipSearch
Searches for <key> in <list>, and returns value if found, or NULL if not. If <plock> is non-NULL, then the lock returned in <plock> will be associated with the...
wdb_keys
this function returns the key and column names for the current database