The m17n Library: Property List

# Property List
[CORE API]

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

## Typedefs
typedef struct 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

Property List objects and API for them.

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

Type of property list objects.

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

## Function Documentation

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 | ( | 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* 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* 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`.

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

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* 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* 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`.

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* 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* 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* 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* 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`.

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.

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`.

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

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.

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.

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.