ConfigEngine使用示例
-
前提:本系统基于公开的原则,采用了Python作为开发语言。因此你需要下载安装Python环境才能运行本系统。
当然,你还需要下载一份最新的ConfEngine配置编译引擎。地址在这里:
http://code.google.com/p/confengine/downloads/list
简要过程如下:
- 步骤1: 下载安装Python运行环境
- 步骤2: 下载ConfEngine最新版本。解开到一个目录中。
- 步骤3: 编写你的配置定义文件 raw.f。
- 步骤4: 调用ConfEngine里的genconf.py编译raw.f,生成raw.h.
- 步骤5: include "raw.h"。 使用AppRaw().来访问你的配置相关的功能。
第一步,定义需要的配置项,保存在raw.f
-
注意这里文件名取为raw.f, 其中的raw会被当作名称的一部分。因此如果你想定义多个独立的配置系统的话,需要精确的选择这个名字。而.f的扩展名,是本系统的建议扩展名,你硬要换也没关系。
raw.f 文件按的类容如下:
-
; System配置范围 s system:account:agnet firefox dd s system:account:username "zhang san" default user name b system:account:remember 0.0 remember last logon user? n system:account:retry 3756 fail count allowed before exit. n system:registered 0 is this copy copyleft? ; 顶级配置项 b lastupdate 12345678 last date for update.
raw.f文件的解释如下:
- 文件的每一行为一个配置项。
- 空行只是为了添加可读性,实际处理被略过。
- 以分号开始的行为注释行,实际处理也被略过。
- 配置项的每一行,分为3~4个列,每一列用空白(空格或者Tab)分开。
-
第一列为单个字符,表明数据类型,如s表示字符串;b表示布尔值;n表示数值。
第二列为可分层次的配置项。每一层之间用:区分(早期曾用'/'区分,但是在某些环境下引起歧义,新版本改为用':')。
- 分层可以理解为按名字空间组织。
- 层间用':'分割,最后一项为实际配置项
- 也可以不使用分层,直接使用配置项。
- 注意不要混合层名字和配置项名字。
- 如:如果定义了system:account:username
- 配置项为username, 他的层次为system.account。
- 这个时候你仍可以定义其他的层次,和其他层次的配置项,如 system:agent:proxy;或者system:lastupdate。
- 但是不能再定义 system:account了。因为account已经是system的子层次,不能再是配置项了。
第三列为默认值。注意列是由空白分开的,所以如果默认值中包含空格的话(字符串类型),就需要用双引号包含起来。类似长路径名的处理。
第四列是可选的,表示注释项。注意这是最后一项,因此不再考虑空白区分,所有第三列以后的剩余内容,都认为是第四列的。
-
- 目前只支持s, b, n三种类型,大概可以涵盖绝大部分的用途了。
-
第二步,调用ConfEngine编译raw.f。 如:E:/confengine/genconf.py E:/dev/marvel/raw.f
-
genconf.py 编译raw.f后,如果raw.f没有语法错误,会生成raw.h(注意名称一致)。同时如果需要的话,会拷贝一份公用类定义文件baseconf.h到raw.h的目录。
可以手工运行,可以看看他的命令行输出的信息。 了解这个过程后,就可以直接把raw.f文件和genconf.py关联起来,没必要每次手工运行了。
这里有三个文件:
raw.f
raw.h
baseconf.h。
raw.f是你的定义文件,应该加入到你的工程里面。如果有版本管理系统的话,也应该加入到版本管理系统里面。
raw.h 和 baseconf.h 是编译raw.f产生的文件,就像编译 .cpp产生的.obj文件一样,是没必要加入到工程和版本管理里面的。
-
有时候.h不加入到工程里面,他里面的代码自动完成提示就不完全。这个时候可以将raw.h和baseconf.h加入到工程里。
加raw.h或者baseconf.h或者同时加入到工程,视你的习惯而定。他们仅仅起自动完成提示的作用,除此外,是完全不必加入到工程里面的。
加入到代码管理则是完全不必要的,因为他的内容完全决定于raw.f。
生成的baseconf.h是公用类容,不必理会。生成的raw.h是你要的内容, 最好include到你的全局头文件定义里。 如stdafx.h 或者 YourApp.h 等里面。
建议:
将raw.f 加入你的工程,然后设定自定义编译选项,这样子每次修改raw.f,编译时就能自动即时的反应更改了。 设定自定义编译选项,VC6的操作如下:在Project的FileView中,选择raw.f, 右键点击弹出上下文菜单,选择settings;在打开的project settings里,选择 custom build 选项页。 在commands里面,输入编译命令, 如 genconf.py $(InputName), outputs里面,填入生成的文件,这里是raw.h。确定即可。
这里genconf.py假定在可以找到的目录下,否则要加上全路径。
raw.h里面会定义一个 AppRaw();的函数(),其中App是固定前缀,Raw来自于定义文件。 这个函数会返回一个CRaw& 类引用。 类的名称一看就知道,而类的类容则包含了配置项的所有内容。
-
第三步,享受你轻便简洁的配置访问功能。
- 示例如下:
-
当然,先要包含头文件。 #include "raw.h"
在程序初始化时,载入全局配置项。代码为
AppRaw().LoadGlobal();
你可以选择是否继续载入其他的用户或者OEM自定义项,如:
AppRaw().LoadUserProfile("lenovo.conf");
AppRaw().LoadUserProfile("Optimization.conf");
可以直接或间接的访问配置项:
int i = AppRaw().system.account.retry;
if (3 < AppRaw().system.account.retry) ...;
- 注意到没有,代码一目了然的逻辑层次,体现了层次分明的配置项的强大优势。
- 而且,你无需记住配置的详细内容,由于有层次,只需要打一个点,自动完成就会列出接下来的所有项。
不止是读取这么简单,你还可以修改它:
AppRaw().system.account.retry = 33;
或者在弹出系统选项设置对话框时,你还可以提供一个复位(恢复默认值)的按钮,同样很简单。只需要调用配置项的reset即可:
AppRaw().system.account.retry.Reset();
或者你不想挨个复位每个配置项,你可以一次复位一个层次的所有配置项,如:
AppRaw().system.account.Reset();
或者调用顶层的reset,复位所有的配置项:
AppRaw().Reset();
在修改了你的配置,或者复位了一些项之后,你需要将配置保存到配置文件中。
你可以调用:
AppRaw().WriteGlobalProfile();
保存一份全局配置文件。 也可以仅仅是保存用户修改部分,作为用户配置文件,如:
AppRaw().WriteUserProfile("Optimization.conf");
- 全局配置文件和用户配置文件的区别
-
1. 全局配置文件只有一个;用户配置文件数目不限。
3. 全局配置文件保存了所有的配置项,不管是否是默认值;用户配置文件仅保存不是默认值的配置项。
4. 由于用户配置文件需要指定名字,因此需要特别注意读取和保存的文件名的一致。
2. 全局配置文件名字固定为exe的名字,仅扩展名变为.conf,因此无需指定;用户配置文件需要指定名字,但是需要注意到不要跟exe名字相同,因为全局配置文件已经占用了这个名字。
-
- 用户配置文件可以不带路径,默认是在.exe所在目录下。但是带完整路径也是可以的。
-
后记,看看最终用户看到配置文件是什么样子的:
-
注:下面的配置文件并不是来源于raw.f。而是来自于一个真实的项目的一小部分,这些内容全是由配置引擎完成的,程序员完全无需关注。可以看到他完备的注释让最终用户也一目了然。
# 主窗口位置左, Default value: 0
MainWnd:Area:l=363
# 主窗口位置上, Default value: 0
MainWnd:Area:t=140
# 主窗口位置又, Default value: 800
MainWnd:Area:r=1386
# 主窗口位置下, Default value: 600
MainWnd:Area:b=967
# 浮动窗口方式 0: 自动隐藏,漂浮在鼠标位置; 1: 固定位置显示; 2: 停靠在主窗口右侧; 3: 停靠在主窗口下侧; 4: 停靠在主窗口上侧, Default value: 1
FloatWnd:Dock=1
# 浮动窗口自动隐藏模式位置宽, Default value: 700
FloatWnd:ModeAuto:cx=700
# 浮动窗口自动隐藏模式位置高, Default value: 300
FloatWnd:ModeAuto:cy=300
# 浮动窗口固定模式位置左, Default value: 700
FloatWnd:ModeFix:l=700
# 浮动窗口固定模式位置上, Default value: 300
FloatWnd:ModeFix:t=300
# 浮动窗口固定模式位置又, Default value: 1024
FloatWnd:ModeFix:r=1024
# 浮动窗口固定模式位置下, Default value: 500
FloatWnd:ModeFix:b=500
# 浮动窗口右侧停靠模式宽, Default value: 500
FloatWnd:ModeRight:cx=500
# 浮动窗口下侧停靠模式高, Default value: 500
FloatWnd:ModeBottom:cy=500
# 浮动窗口上侧停靠模式高, Default value: 700
FloatWnd:ModeTop:cy=700