Menu
▾
▴
Tree [416e48] master / History
Allen Tse
Read Me
Unicode. 简体中文见后半部分
/***************************************************************************
* *
* Explicit Distribution Declaration *
* This program is not welcomed to be modified or used by, or, if *
* possible, redistributed to people who discriminate against people *
* based solely on race, gender or sexual orientation. *
* *
***************************************************************************/
/***************************************************************************
Copyright 2010 Allen Tse
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
***************************************************************************/
/***************************************************************************
If provided, too, COPYING is used by automake, autoconf, autotools.
***************************************************************************/
EZ Common is the library serving other parts of EZ Project, defining common
types, I/O functionalities and configuration file operations.
EZ Project uses an enum type to define function return values.
The possiblities are, critical errors, minor errors, no significant errors,
right and unknown. Please turn to header file for their comments.
ezoi is a standard I/O class for screen or file(s). After the construction
of an object, file() can assign file for I/O by file names (if a failure is
returned, the file cannot be opened.) and mod() can be envoked to tell every
ezoi's interactions to prefix a string. Two inpt() are for input, one for
string and one for single character. If only one character is needed for
an input, it is forced to screen, and no Enter's required. dsp() is the common
interface to output in format. mem() is for more specific usage. Use ind()
to output in raw, though in format, too, directly. To minimize the dependency
of the library caller and the library implementation, ezoip member is defined
inside ezoi to shield private details.
ezcfg is a standard XML class for configuration operations. It uses TinyXML
(refer to tinyxml.txt for more information) and packs TinyXML's classes inside
so that ezcfg's user need not to use TinyXML directly and thus makes ezcfg
a more independant way of manipulating configuration files. Use the class'
free member to release the memory allocated by ezcfg.
If constructor's parameter is a file name, that file is loaded. The current
node will be the document. If the constructor with two or more parameters are
used, a configuration file is created (but not saved yet when constructed).
The parameters include at least root element name and the version string in
the declaration. The encoding and the standalone string in the declaration,
and a comment between the declaration and root element, can be included in the
parameter list. The root element's name defaults to EZ_Project and the version
string in the declaration defaults to 1.0. After the creation, the current
node will be the root element.
getType() returns current node's type, a declaration, an element, text, or
comment. And whether the file cannot be loaded or just loaded before reaching
any nodes can be differed, too. next() move to the next node, whose return
value means whether the node does not exist, is level(s) up, is one level
down, or is at the same level. A parameter can be given to denote that only
same or upper level nodes are wanted. more() is to create a node, whose
parameters are similar to the return values of next(). Even if a higher level
(described below) is requested, the root element will not be exceeded.
Declaration cannot be set after constructed but will be fetched after a file
is loaded. save() saves the configurations to a file. Its parameter is the
file's name. If no parameter is provided, the file that the instance
previously operates on is used for saving. Its return notates whether the
saving actoin is successful.
The first parameter of getDeclarationAttributes() returns an attribute value
in declaration and the second parameter notates which attribute it is, which
defaults to the first attribute. This function returns this attribute's type,
version, encoding, standalone, count, or not available. For other nodes, the
first parameters of getValue() and getAttribute() return current elements' names
and their attributes' names respectively. The second parameter of
getAttribute() returns the attribute's value and if a third parameter is
provided, the fetched attribute is the first, not the next. setValue() and
setAttribute() are corresponding functions to set the elements' names and their
attributes' names and values. remove() removes current node and
removeAttribute removes the attribute whose name is same as the first
parameter.
setBookmark() assign the current position a name and getBookmark() moves to
the corresponding position later. If no parameter is provided when calling
getBookmark(), the current position is like the file is just loaded.
level() returns current node level or go to specific UPPER level and returns
the level after moving. The invalid level value is levelNA. The upper most
level value is levelFirst. Every node's level is equal or bigger than
levelFirst.
Since mutex is platform-dependant, users of these classes have to implement
related feature, if needed.
For Linux/Unix users, refer to INSTALL for detailed information on
installation method.
For Windows users, *.vcproj and *.vcxproj is Visual C++'s project file for
compilation.
For other platforms, I am afraid I have no idea to and how to support them.
Allen Tse
Nov. 1, 2010
/***************************************************************************
* *
* 明确发布声明 *
* 本程序不欢迎对人有种族、性别或性取向歧视的人士修改、使用，且如果 *
* 可能的话也不宜向其传播。 *
* *
***************************************************************************/
/***************************************************************************
版权 2010 Allen Tse
本文件以the Apache License, Version 2.0（以下简称授权）授权（以下中文翻译
并非官方翻译，仅供参考，表义以英文原文为准）。
您不能够以不遵守授权的方式使用文件。
您可以可以从以下地址得到授权的拷贝：
http://www.apache.org/licenses/LICENSE-2.0
除非写明由于执行法律或或同意的需要，以授权发布的软件基于“本形式”，无论
显式或隐式，都没有任何形式的保证或条件。授权中关于特定语言的许可和限制，
详见授权原文。
***************************************************************************/
/***************************************************************************
（如果也提供，）COPYING是automake, autoconf, autotools使用的。
***************************************************************************/
易公共是为其它易项目的部分服务的库。它定义了公用类型、输入输出功能和配置
操作。
易项目使用一个枚举类型定义函数返回值。其可能取值有：严重错误、非重大错误、
无明显错误、正确和未知。请参考头文件中的注释。
ezoi是为标准化屏幕或文件的输入输出编写的类。在生成对象后，可以调用file函数
分别指定输入输出所使用文件的文件名（如果返回失败则表示无法打开该文件）；可以
调用mod函数来为每个ezoi的交互设定前缀。有两个inpt函数用于输入，分别用于字符串
和单个字符。如果只需要输入单个字符，则会强制进行屏幕交互，而且不需要输入回车。
dsp是格式化输出的一般接口函数。mem函数则用于更特定的用途。用ind函数能以原始
内存直接输出，不过也是经过格式化的。为减少库调用者对库实现的依赖，成员ezoip
被定义在ezoi内部，从而屏蔽内部细节。
ezcfg是标准XML类，用于配置操作。它使用并封装TinyXML（详见tinyxml.txt），
使得ezcfg的使用都不必直接调用TinyXML，进而使ezcfg成为更独立的操作配置文件的
方式。
构造函数的参数带有文件名时，会打开对应文件，当前节点是文件。构造函数带
两个或更多参数时，建立一个配置文件（但构造时不保存）。这时必需的参数是
根节点名称和声明中的版本字符串，可选参数是声明中的编码字符串、独立字符串，
和声明与根节点之间的注释。根节点名称默认为“EZ_Project”，声明中的版本默认为
“1.0”。这种情况下，当前节点是根节点。
getType函数返回当前节点的类型，可以是声明、元素、字符或注释，也可以表明
文件无法读入或刚读入还未进行到节点。next函数用于移动到下一节点，返回值表示
再没有节点、已经上退一级、已经下进一级或平级移动。也可以指明需要哪种类型的
节点，作为参数。more函数用于创建一个节点，参数与next函数的返回值相仿。在构造
之后，无法设置声明；在读入文件后，移动访问节点过程中会取到声明。save函数用于保存
文件，参数是文件名。如果没有参数，则为上次操作的文件。其返回值表明是否成功保
存了。
getDeclarationAttributes函数的第一个参数返回声明中的一个属性值，第二个参
数指明它是哪个属性，默认为第一个属性。函数返回该属性的类型：版本、编码、独
立、计数或不可用。对于其它节点，getValue函数和getAttribute函数的第一个参数
返回元素或属性的名称。getAttribute函数的第二个参数返回属性值。如果有第三个
参数，则取出第一个属性，而非下一个。对应的，setValue函数和setAttribute函数设
置元素名称和属性名称、取值。remove函数用于删除当前节点，removeAttribute函数
用于删除第一个参数指定的属性名的属性。
setBookmark函数将当前位置设置一个名称，而getBookmark函数可以移到到对应位
置。如果不带参数调用getBookmark函数，则当前位置与文件刚读入时位置相同。
level函数返回当前节点层次，或，移动到指定的“更高”层次并返回移动后的层
次。非法层次取值为levelNA。最高层次取值为levelFirst。所有节点的层次大于等于
levelFirst。
由于互斥锁是平台相关的，如果需要，这些类的使用者只能自己实现。
对于Linux或Unix用户，INSTALL（英文）中写了详细的安装方法。
对于Windows用户，后缀名为vcproj和vcxproj的文件是Visual C++的项目文件，
用于编译。
对于其它平台，我恐怕不知道怎么做，也不打算支持。
谢威扬
二○一○年十一月一日
