/* Copyright (C) 2003, 2004
     National Institute of Advanced Industrial Science and Technology (AIST)
     Registration Number H15PRO112
   See the end for copying conditions.  */

/***en

@page mdbGeneral General Format

@section general-description DESCRIPTION

The mdatabase_load () function returns the data specified by tags in
the form of plist if the first tag is not @c Mchartable nor @c
Mcharset.  The keys of the returned plist are limited to
<tt>Minteger</tt>, <tt>Msymbol</tt>, <tt>Mtext</tt>, and
<tt>Mplist</tt>.  The type of the value is unambiguously determined by
the corresponding key.  If the key is <tt>Minteger</tt>, the value is
an integer.  If the key is <tt>Msymbol</tt>, the value is a symbol.
And so on.

A number of expressions are possible to represent a plist.  For
instance, we can use the form <tt>(K1:V1, K2:V2, ..., Kn:Vn)</tt> to
represent a plist whose first property key and value are K1 and V1,
second key and value are K2 and V2, and so on.  However, we can use a
simpler expression here because the types of plists used in the m17n
database are fairly restricted.

Hereafter, we use an expression, which is similar to S-expression, to
represent a plist.  (Actually, the default database loader of the m17n
library is designed to read data files written in this expression.)

The expression consists of one or more <i>elements</i>.  Each element
represents a property, i.e. a single element of a plist.

Elements are separated by one or more <i>whitespaces</i>, i.e. a space
(code 32), a tab (code 9), or a newline (code 10).  Comments begin
with a semicolon (<tt>;</tt>) and extend to the end of the line.

The key and the value of each property are determined based on the
type of the element as explained below.

<ul>

<li> INTEGER

An element that matches the regular expression <tt>-?[0-9]+</tt> or
<tt>0[xX][0-9A-Fa-f]+</tt> represents a property whose key is
<tt>Minteger</tt>.  An element matching the former expression is
interpreted as an integer in decimal notation, and one matching the
latter is interpreted as an integer in hexadecimal notation.  The
value of the property is the result of interpretation.

For instance, the element <tt>0xA0</tt> represents a property whose
value is 160 in decimal.

<li> SYMBOL

An element that matches the regular expression
<tt>[^-(0-9]</tt><tt>([^\\()]|\\.)+</tt> represents a property whose key is
<tt> Msymbol</tt>.  In the element, <tt>\\t</tt>, <tt>\\n</tt>,
<tt>\\r</tt>, and <tt>\\e</tt> are replaced with tab (code 9), newline
(code 10), carriage return (code 13), and escape (code 27)
respectively.  Other characters following a backslash is interpreted
as it is.  The value of the property is the symbol having the
resulting string as its name.

For instance, the element <tt>abc\ def</tt> represents a property
whose value is the symbol having the name "abc def".

<li> MTEXT

An element that matches the regular expression <tt>"([^"]|\\")*"</tt>
represents a property whose key is <tt>Mtext</tt>.  The backslash
escape explained above also applies here.  Moreover, each part in the
element matching the regular expression <tt>
\\[xX][0-9A-Fa-f][0-9A-Fa-f]</tt> is replaced with its hexadecimal
interpretation.

After having resolved the backslash escapes, the byte sequence between
the double quotes is interpreted as a UTF-8 sequence and decoded into
an M-text.  This M-text is the value of the property.

<li> PLIST

Zero or more elements surrounded by a pair of parentheses represent a
property whose key is <tt>Mplist</tt>.  Whitespaces before and after a
parenthesis can be omitted.  The value of the property is a plist,
which is the result of recursive interpretation of the elements
between the parentheses.

</ul>

@section general-syntax SYNTAX NOTATION

In an explanation of a plist format of data, a BNF-like notation is
used.  In the notation, non-terminals are represented by a string of
uppercase letters (including '-' in the middle), terminals are
represented by a string surrounded by '"'.  Special non-terminals
INTEGER, SYMBOL, MTEXT and PLIST represents property integer, symbol,
M-text, or plist respectively.

@section general-example EXAMPLE

Here is an example of database data that is read into a plist of this
simple format:

@verbatim
DATA-FORMAT ::=
    [ INTEGER | SYMBOL | MTEXT | FUNC ] *

FUNC ::=
    '(' FUNC-NAME FUNC-ARG * ')'

FUNC-NAME ::=
    SYMBOL

FUNC-ARG ::=
    INTEGER | SYMBOL | MTEXT | '(' FUNC-ARG ')'
@endverbatim

For instance, a data file that contains this text matches the above
syntax:

@verbatim
abc 123 (pqr 0xff) "m\"text" (_\\_ ("string" xyz) -456)
@endverbatim

and is read into this plist:

@verbatim
1st element: key: Msymbol,  value: abc
2nd element: key: Minteger, value: 123
3rd element: key: Mplist,   value: a plist of these elements:
    1st element: key Msymbol,  value: pgr
    2nd element: key Minteger, value: 255
4th element: key: Mtext,    value: m"text
5th element: key: Mplist,   value: a plist of these elements:
    1st element: key: Msymbol, value: _\_
    2nd element: key: Mplist,  value: a plist of these elements:
        1st element: key: Mtext,    value: string
	2nd element: key: Msymbol,  value: xyz
	3rd element: key: Minteger, value: -456
@endverbatim
*/

/* 
Copyright (C) 2003, 2004
  National Institute of Advanced Industrial Science and Technology (AIST)
  Registration Number H15PRO112

This file is part of the m17n database; a sub-part of the m17n
library.

The m17n library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public License
as published by the Free Software Foundation; either version 2.1 of
the License, or (at your option) any later version.

The m17n library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with the m17n library; if not, write to the Free
Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
*/
