xnm.h File Reference

The libxnm header file. More...

#include <glib.h>

Go to the source code of this file.

Data Structures

struct  XnmValue

Enumerations

enum  { XNM_ERROR = 0, XNM_ERROR_SYNTAX_ERROR = 1, XNM_ERROR_KEY_NOT_FOUND = 2 }
enum  XnmValueType {
  XNM_UNKNOWN, XNM_TABLE, XNM_ARRAY, XNM_STRING,
  XNM_BINARY
}
enum  XnmValueGetType {
  XNM_GET_UINT8, XNM_GET_UINT16, XNM_GET_UINT, XNM_GET_UINT32,
  XNM_GET_INT8, XNM_GET_INT16, XNM_GET_INT, XNM_GET_INT32,
  XNM_GET_INT64, XNM_GET_FLOAT, XNM_GET_DOUBLE, XNM_GET_STRING,
  XNM_GET_BOOL
}

Functions

XnmValue * xnm_value_new_string (const gchar *s)
XnmValue * xnm_value_new_table ()
XnmValue * xnm_value_new_array ()
XnmValue * xnm_value_new_binary (const gchar *buf, size_t size)
void xnm_value_ref (XnmValue *xnm_value)
void xnm_value_unref (XnmValue *xnm_value)
gchar * xnm_value_export_to_string (XnmValue *xnm_value)
int xnm_value_get (XnmValue *xnm_value_tree, const char *key, XnmValue **xnm_value)
int xnm_value_get_string (XnmValue *xnm_value, const char *key, gchar **string_val)
int xnm_value_get_const_string (XnmValue *xnm_value_tree, const char *key, const gchar **const_val_string)
int xnm_value_get_int (XnmValue *xnm_value, const char *key, int *val_int)
int xnm_value_get_bool (XnmValue *xnm_value, const char *key, gboolean *val_bool)
int xnm_value_array_push_value (XnmValue *xnm_value_array, XnmValue *value)
int xnm_value_array_push_string (XnmValue *xnm_value_array, const gchar *string)
int xnm_value_array_push_int (XnmValue *xnm_value_array, int value_int)
int xnm_value_array_push_printf (XnmValue *xnm_value_array, const gchar *format,...)
int xnm_value_table_set_key_value (XnmValue *xnm_value_tree, const gchar *key, XnmValue *xnm_value)
int xnm_value_table_set_key_value_string (XnmValue *xnm_value_parent, const gchar *key, const gchar *string)
int xnm_value_set_key_value_printf (XnmValue *xnm_value_parent, const gchar *key, const gchar *format,...)
int xnm_value_get_array_length (XnmValue *xnm_value, const char *key)
int xnm_value_get_values (XnmValue *xnm_value,...)
int xnm_value_get_table_key_list (XnmValue *xnm_value, const char *key, const GPtrArray **key_list)
int xnm_parse_string (const gchar *string, XnmValue **value, GError **error)
int xnm_parse_string_len (const gchar *string, int len, XnmValue **value, GError **error)
int xnm_parse_file (const gchar *filenam, XnmValue **xnm_value, GError **error)

Detailed Description

The libxnm header file.

Author:
Dov Grobgeld <dov.grobgeld@gmail.com>
Date:
Fri Jan 12 09:23:04 2007
The libxnm library stores the xnm data in a tree of XnmValue's where each XnmValue dynamically may contain a string, a binary buffer, an array or a table.

Values are accessed by their keys which is a slash separated path description from the root to a value. Tables are dereferenced by the key name, and arrays by the array index enclosed in square brackets.

Given a xnm structure that looks like:

   gaim => {
     gtk=> {
       browsers=> {
         place=>F
           command=>"xterm -e lynx %s"
           browser=>firefox
           new_window=>F
       }
       plugins => [
         '/usr/lib/gaim/gaimrc.so'
           '/usr/lib/gaim/ssl-nss.so'
           '/usr/lib/gaim/ssl.so'
       ]
     }
     pos => [ {x=>0 y=>0} {x=>100 y=0} {x=>100 y=>50 } ]
   }

Here are a couple of valid keys

Most commands are made to ignore undefined keys.

libxnm provides several methods for extracting values from an xnm tree that all start with xnm_get .

Enumeration Type Documentation

anonymous enum

Error definitions

enum XnmValueGetType

Values used when retrieving. Note that binary values may not be extracted this way, as they need to have the length of them returned as well.

enum XnmValueType

The possible types of a XnmValue.

Function Documentation

int xnm_parse_file ( const gchar *  filenam,
XnmValue **  xnm_value,
GError **  error 
)

Read a file and parse it.

Parameters:
filenam 
xnm_value 
error 
Returns:

int xnm_parse_string ( const gchar *  string,
XnmValue **  value,
GError **  error 
)

Parse a string in XNM syntax.

Parameters:
string A string in xnm format
Return values:
value A newly allocated XnmValue if the parsing was successful.
error Error if parsing failed.
Returns:

int xnm_parse_string_len ( const gchar *  string,
int  len,
XnmValue **  value,
GError **  error 
)

Parse a string in asf format with a given len.

Parameters:
string 
len 
value 
error 
Returns:

int xnm_value_array_push_int ( XnmValue *  xnm_value_array,
int  value_int 
)

Push an integer value into an xnm value of type array.

Parameters:
xnm_value_array 
value_int 
Returns:

int xnm_value_array_push_printf ( XnmValue *  xnm_value_array,
const gchar *  format,
  ... 
)

Formatted addition to an array. Use e.g. for doubles.

Parameters:
xnm_value_array 
format 
Returns:

int xnm_value_array_push_string ( XnmValue *  xnm_value_array,
const gchar *  string 
)

Push a string into an xnm value of type array.

Parameters:
xnm_value_array 
string 
Returns:

int xnm_value_array_push_value ( XnmValue *  xnm_value_array,
XnmValue *  value 
)

Add an xnm_value into an XnmValue of type array.

Returns:

gchar* xnm_value_export_to_string ( XnmValue *  xnm_value  ) 

Allocate a new string containing a serialized representation of xnm_value.

Parameters:
xnm_value 
Returns:

int xnm_value_get ( XnmValue *  xnm_value_tree,
const char *  key,
XnmValue **  xnm_value 
)

Retrieve an xnm value from an xnm_value_tree. If the key is not found then the value is not assigned. If the key is found then xnm_value is assigned the corresponding string.

Note that xnm_value_get does *not* dereference xnm_value before overwriting it with a new value.

The returned xnm_value points into the xnm_value_tree with an increased reference count.

Parameters:
xnm_value_tree 
key 
xnm_value 
Returns:
0 if value retrieved, -1 if value not found, -2 if key syntax error.

int xnm_value_get_array_length ( XnmValue *  xnm_value,
const char *  key 
)

Retrive the length of a XnmValue array.

Parameters:
xnm_value 
key 
Returns:
Length of array if node found. -1 if key not found or if xnm_value is not an array.

int xnm_value_get_bool ( XnmValue *  xnm_value,
const char *  key,
gboolean *  val_bool 
)

Retrieve a boolean value from an xnm_value. The boolean value is considered true if it starts with 't','T','y','Y', or 1. Everything else is false.

int xnm_value_get_const_string ( XnmValue *  xnm_value_tree,
const char *  key,
const gchar **  const_val_string 
)

This value retrieves a const pointer to the string within the xnm_value_tree.

Parameters:
xnm_value_tree 
key 
Return values:
const_val_string 
Returns:
0 if value retrieved, -1 if value not found, -2 if key syntax error.

int xnm_value_get_int ( XnmValue *  xnm_value,
const char *  key,
int *  val_int 
)

This value retrieves a value from an xnm_value and turns it into an integer with atoi().

Parameters:
xnm_value 
key 
Return values:
val_int 
Returns:
0 if value retrieved, -1 if value not found, -2 if key syntax error.

int xnm_value_get_string ( XnmValue *  xnm_value,
const char *  key,
gchar **  string_val 
)

This value retrieves a string from an xnm_value_tree. If the key is found then string_value is freed, and the string is copied into string_val. Otherwise, string_val is left untouched.

Parameters:
xnm_value 
key 
string_val 
Returns:
0 if value retrieved, -1 if value not found, -2 if key syntax error.

int xnm_value_get_table_key_list ( XnmValue *  xnm_value,
const char *  key,
const GPtrArray **  key_list 
)

Get a list of all keys of a table.

Parameters:
xnm_value 
key 
key_list 
Returns:

int xnm_value_get_values ( XnmValue *  xnm_value,
  ... 
)

Get a list of values in one call. This function is very convenient for extracting multiple values in one call. It takes as argument a NULL terminated vararg list, where each value extraction is controlled by three arguments:

  • The key - A still containing the path to the node to get info from
  • The type the third argument. This value is of type |XnmValueGetType|.
  • A pointer to where to store the value.

Parameters:
xnm_value 
Returns:

XnmValue* xnm_value_new_array (  ) 

Allocate a new XnmValue with the type XNM_ARRAY.

Returns:

XnmValue* xnm_value_new_binary ( const gchar *  buf,
size_t  size 
)

Allocate a new XnmValue with the type binary and initiate it with the data in buf.

XnmValue* xnm_value_new_string ( const gchar *  s  ) 

Allocate a new XnmValue with the type string. The string is initialized to a copy of s.

Parameters:
s 
Returns:
Newly allocated XnmValue

XnmValue* xnm_value_new_table (  ) 

Allocate a new XnmValue with the type XNM_TABLE.

Returns:

void xnm_value_ref ( XnmValue *  xnm_value  ) 

Increase the reference count of xnm_value.

Parameters:
xnm_value 

int xnm_value_set_key_value_printf ( XnmValue *  xnm_value_parent,
const gchar *  key,
const gchar *  format,
  ... 
)

Set a key value which is formatted with printf.

Parameters:
xnm_value_parent 
key 
format 
Returns:

int xnm_value_table_set_key_value ( XnmValue *  xnm_value_tree,
const gchar *  key,
XnmValue *  xnm_value 
)

Add a xnm_value to a xnm table. This function increases the reference count of the xnm_value.

Note! This function does not yet support hierarchical keys. To set an a key that is not a direct parent of xnm_value_tree, the leaf xnm_value table must first be retrieved, and this function then called on that value.

Parameters:
xnm_value_tree 
key 
xnm_value 
Returns:

int xnm_value_table_set_key_value_string ( XnmValue *  xnm_value_parent,
const gchar *  key,
const gchar *  string 
)

Convenience function for setting a string key value. If the key already exists in xnm_value_parent, then it is freed and replaced by the new svalue.

Parameters:
xnm_value_parent 
key 
string 
Returns:

void xnm_value_unref ( XnmValue *  xnm_value  ) 

Decrease the reference count on an xnm_value. If the reference count goes down to 0, the value is destroyed.

Parameters:
xnm_value 

Generated on Thu Dec 25 10:36:27 2008 by  doxygen 1.5.7.1