Main Page Modules Data Structures Globals Appendix

Property List
[CORE API]

Property List objects and API for them. More...


Typedefs
typedef MPlist	MPlist
	Type of property list objects.
Functions
MPlist *	mplist_deserialize (MText *mt)
	Generate a property list by deserializing an M-text.
MPlist *	mplist (void)
	Create a property list object.
MPlist *	mplist_copy (MPlist *plist)
	Copy a property list.
MPlist *	mplist_put (MPlist plist, MSymbol key, void val)
	Set the value of a property in a property list.
void *	mplist_get (MPlist *plist, MSymbol key)
	Get the value of a property in a property list.
MPlist *	mplist_put_func (MPlist *plist, MSymbol key, M17NFunc func)
	Set the value (function pointer) of a property in a property list.
M17NFunc	mplist_get_func (MPlist *plist, MSymbol key)
	Get the value (function pointer) of a property in a property list.
MPlist *	mplist_add (MPlist plist, MSymbol key, void val)
	Add a property at the end of a property list.
MPlist *	mplist_push (MPlist plist, MSymbol key, void val)
	Add a property at the beginning of a property list.
void *	mplist_pop (MPlist *plist)
	Remove a property at the beginning of a property list.
MPlist *	mplist_find_by_key (MPlist *plist, MSymbol key)
	Find a property of a specific key in a property list.
MPlist *	mplist_find_by_value (MPlist plist, void val)
	Find a property of a specific value in a property list.
MPlist *	mplist_next (MPlist *plist)
	Return the next sublist of a property list.
MPlist *	mplist_set (MPlist plist, MSymbol key, void val)
	Set the first property in a property list.
int	mplist_length (MPlist *plist)
	Return the length of a property list.
MSymbol	mplist_key (MPlist *plist)
	Return the key of the first property in a property list.
void *	mplist_value (MPlist *plist)
	Return the value of the first property in a property list.
Variables
MSymbol	Minteger
	Symbol whose name is "integer".
MSymbol	Mplist
	Symbol whose name is "plist".
MSymbol	Mtext
	Symbol whose name is "mtext".

Detailed Description

A property list (or plist for short) is a list of zero or more properties. A property consists of a key and a value, where key is a symbol and value is anything that can be cast to (void *).

If the key of a property is a managing key, its value is a managed object. A property list itself is a managed objects.

If each key of a plist is one of Msymbol, Mtext, Minteger, and Mplist, the plist is called as well-formed and represented by the following notation in the documentation.

      PLIST ::= '(' ELEMENT * ')'

      ELEMENT ::= INTEGER | SYMBOL | M-TEXT | PLIST

      M-TEXT ::= '"' text data ... '"'

For instance, if a plist has four elements; integer -20, symbol of name "sym", M-text of contents "abc", and plist of integer 10 and symbol of name "another-symbol", it is represented as this:

(-20 sym "abc" (10 another-symbol))

Typedef Documentation

typedef struct MPlist MPlist

The type MPlist is for a property list object. Its internal structure is concealed from application programs.

Function Documentation

MPlist * mplist_deserialize ( MText * mt )

The mplist_deserialize() function parses M-text mt and returns a property list.

The syntax of mt is as follows.

MT ::= '(' ELEMENT * ')'

ELEMENT ::= SYMBOL | INTEGER | M-TEXT | PLIST

SYMBOL ::= ascii-character-sequence

INTEGER ::= '-' ? [ '0' | .. | '9' ]+ | '0x' [ '0' | .. | '9' | 'A' | .. | 'F' | 'a' | .. | 'f' ]+

M-TEXT ::= '"' character-sequence '"'

Each alternatives of ELEMENT is assigned one of these keys: Msymbol, Minteger, Mtext, Mplist

In an ascii-character-sequence, a backslash (\) is used as the escape character, which means that, for instance, "abc\ def" produces a symbol whose name is of length seven with the fourth character being a space.

MPlist* mplist ( void )

The mplist() function returns a newly created property list object of length zero.

Return value:: This function returns a newly created property list.

Errors:: This function never fails.

MPlist* mplist_copy ( MPlist * plist )

The mplist_copy() function copies property list plist. In the copy, the values are the same as those of plist.

Return value:: This function returns a newly created plist which is a copy of plist.

Errors:: This function never fails.

MPlist* mplist_put	(	MPlist *	plist,
		MSymbol	key,
		void *	val
	)

The mplist_put() function searches property list plist from the beginning for a property whose key is key. If such a property is found, its value is changed to value. Otherwise, a new property whose key is key and value is value is appended at the end of plist. See the documentation of mplist_add() for the restriction on key and val.

If key is a managing key, val must be a managed object. In this case, the reference count of the old value, if not NULL, is decremented by one, and that of val is incremented by one.

Return value:: If the operation was successful, mplist_put() returns a sublist of plist whose first element is the just modified or added one. Otherwise, it returns NULL.

void* mplist_get	(	MPlist *	plist,
		MSymbol	key
	)

The mplist_get() function searches property list plist from the beginning for a property whose key is key. If such a property is found, its value is returned as the type of (void *). If not found, NULL is returned.

When NULL is returned, there are two possibilities: one is the case where no property is found (see above); the other is the case where a property is found and its value is NULL. In case that these two cases must be distinguished, use the mplist_find_by_key() function.

See Also:: mplist_find_by_key()

MPlist* mplist_put_func	(	MPlist *	plist,
		MSymbol	key,
		M17NFunc	func
	)

The mplist_put_func() function is similar to mplist_put() but for setting function pointer func in property list plist for key key. key must not be a managing key.

See Also:: mplist_put(), M17N_FUNC()

M17NFunc mplist_get_func	(	MPlist *	plist,
		MSymbol	key
	)

The mplist_get_func() function is similar to mplist_get() but for getting a function pointer from property list plist by key key.

See Also:: mplist_get()

MPlist* mplist_add	(	MPlist *	plist,
		MSymbol	key,
		void *	val
	)

The mplist_add() function appends at the end of property list plist a property whose key is key and value is val. key can be any symbol other than Mnil.

If key is a managing key, val must be a managed object. In this case, the reference count of val is incremented by one.

Return value:: If the operation was successful, mplist_add() returns a sublist of plist whose first element is the just added one. Otherwise, it returns NULL.

MPlist* mplist_push	(	MPlist *	plist,
		MSymbol	key,
		void *	val
	)

The mplist_push() function inserts at the beginning of property list plist a property whose key is key and value is val.

If key is a managing key, val must be a managed object. In this case, the reference count of val is incremented by one.

Return value:: If the operation was successful, this function returns plist. Otherwise, it returns NULL.

void* mplist_pop ( MPlist * plist )

The mplist_pop() function removes a property at the beginning of property list plist. As a result, the second key and value of the plist become the first ones.

Return value:: If the operation was successful, this function return the value of the just popped property. Otherwise, it returns NULL.

MPlist* mplist_find_by_key	(	MPlist *	plist,
		MSymbol	key
	)

The mplist_find_by_key() function searches property list plist from the beginning for a property whose key is key. If such a property is found, a sublist of plist whose first element is the found one is returned. Otherwise, NULL is returned.

If key is Mnil, it returns a sublist of plist whose first element is the last one of plist.

MPlist* mplist_find_by_value	(	MPlist *	plist,
		void *	val
	)

The mplist_find_by_value() function searches property list plist from the beginning for a property whose value is val. If such a property is found, a sublist of plist whose first element is the found one is returned. Otherwise, NULL is returned.

MPlist* mplist_next ( MPlist * plist )

The mplist_next() function returns a pointer to the sublist of property list plist, which begins at the second element in plist. If the length of plist is zero, it returns NULL.

MPlist* mplist_set	(	MPlist *	plist,
		MSymbol	key,
		void *	val
	)

The mplist_set() function sets the key and the value of the first property in property list plist to key and value, respectively. See the documentation of mplist_add() for the restriction on key and val.

Return value:: If the operation was successful, mplist_set() returns plist. Otherwise, it returns NULL.

int mplist_length ( MPlist * plist )

The mplist_length() function returns the number of properties in property list plist.

MSymbol mplist_key ( MPlist * plist )

The mplist_key() function returns the key of the first property in property list plist. If the length of plist is zero, it returns Mnil.

void* mplist_value ( MPlist * plist )

The mplist_value() function returns the value of the first property in property list plist. If the length of plist is zero, it returns NULL.

Variable Documentation

MSymbol Minteger

The symbol Minteger has the name "integer". The value of a property whose key is Minteger must be an integer.

MSymbol Mplist

The symbol Mplist has the name "plist". It is a managing key. A value of a property whose key is Mplist must be a plist.

MSymbol Mtext

The symbol Mtext has the name "mtext". It is a managing key. A value of a property whose key is Mtext must be an M-text.

Top of this page

Main Page Modules Data Structures Globals Appendix

Property List [CORE API]

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

Function Documentation

Variable Documentation

Property List
[CORE API]