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

@addtogroup m17nPlist

@brief Property List objects and API for them.

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

If the key of a property is a @e managing @e key, its @e value is
a @e managed @e 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 @e 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))

Function Documentation

◆ mplist_deserialize()

MPlist * mplist_deserialize ( MText * mt )

Generate a property list by deserializing an M-text.

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 * mplist ( void )

Create a property list object.

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_copy()

MPlist * mplist_copy ( MPlist * plist )

Copy a property list.

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_put()

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

Set the value of a property in a property list.

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.

◆ mplist_get()

void * mplist_get	(	MPlist *	plist,
		MSymbol	key
	)

Get the value of a property in a property list.

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_put_func()

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

Set the value (function pointer) of a property in a property list.

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()

◆ mplist_get_func()

M17NFunc mplist_get_func	(	MPlist *	plist,
		MSymbol	key
	)

Get the value (function pointer) of a property in a property list.

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_add()

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

Add a property at the end of a property list.

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_push()

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

Add a property at the beginning of a property list.

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.

◆ mplist_pop()

void * mplist_pop ( MPlist * plist )

Remove a property at the beginning of a property list.

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_find_by_key()

MPlist * mplist_find_by_key	(	MPlist *	plist,
		MSymbol	key
	)

Find a property of a specific key in a property list.

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_find_by_value()

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

Find a property of a specific value in a property list.

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_next()

MPlist * mplist_next ( MPlist * plist )

Return the next sublist of a property list.

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_set()

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

Set the first property in a property list.

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.

◆ mplist_length()

int mplist_length ( MPlist * plist )

Return the length of a property list.

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

◆ mplist_key()

MSymbol mplist_key ( MPlist * plist )

Return the key of the first property in a property list.

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.

◆ mplist_value()

void * mplist_value ( MPlist * plist )

Return the value of the first property in a property list.

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

◆ Minteger

MSymbol Minteger

Symbol whose name is "integer".

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

◆ Mplist

MSymbol Mplist

Symbol whose name is "plist".

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.

◆ Mtext

MSymbol Mtext

Symbol whose name is "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.

Functions

Variables