阿九文本(a9text v3.1)

标题:: 阿九文本(a9text v3.1)
作者:: 史荣久
授权:: 共同创作
声明:: 无担保无保证:)
创建:: 2007-07-07
修改:: 2007-07-11
================================================================================

目录
    1.      功能介绍
   
    2.      基本约定
    2.1.    字符(char)
    2.1.1.  字符:空白(char_blank)
    2.1.2.  字符:换行(char_line)
    2.1.3.  字符:转义(char_escape)
    2.2.    模式(mode)
    2.2.1.  模式:修饰(mode_trig)
    2.2.2.  模式:链入(mode_join)
    2.2.3.  模式:链出(mode_link)
    2.2.4.  模式:文本(mode_text)
    2.3.    区域(area)
    2.4.    段落(para/paragraph)
    2.4.1.  段落:空行(para_blank)
    2.4.2.  段落:横线(para_line)
    2.5.    字典(dict)
    2.6.    列表(list)
    2.7.    章节(sect/section)
    2.8.    根(root)
   
    3.      区域扩展
    3.1.    区域:文本
    3.2.    区域:加密(area_secret)
    3.3.    区域:表格
    3.4.    区域:*HTML
   
    4.      约定图谱
    4.1.    约定包含图
    4.2.    约定结构图
   
    5.      文本处理
    5.1.    段落
    5.2.    空白
    5.3.    缩进

--------------------------------------------------------------------------------

1. 功能介绍
    a9text是一组文本格式的约定.
    用来提高文本文档的可读性和转换性.

2. 基本约定
  
   为表达方便,这里为ABNF范式(RFC2234)扩展了个正则表达式(regexp)模式,
   完全类似字符串(strings)模式,即,允许在双"/"间直接使用正则表达式.
  
   例如:
   rule1 = /^a*$/
   rule2 = /^/ *"a" /$/
  
   通用规则:
   head_blank = /^[\u0009\u0020\u3000]+/  ;行首空白(/^/ *char_blank)
   digit   = /[0-9]+/
   hexdig  = /[0-9a-fA-F]+/
  
2.1. 字符(char)
    char = /./  ; any char
   
    "字符",是指任意unicode字符集,除以下特殊用途外,所有字符无差别对待.
   
2.1.1. 字符:空白(char_blank)
    char_blank = %x09 / %x20 / %x3000
   
    "字符:空白",是指"水平制表符(u0009)","半角空格(u0020)","全角空格(u3000)".
    a9text的空白处理是基于"半角空格(u0020)"的.
    其中,"全角空格"等效于2个"半角空格","水平制表符"等效于4个"半角空格".
    行首空白的等效"半角空格"数量称为以一个"缩进量(indent)"
   
2.1.2. 字符:换行(char_line)
    char_line = %x0A / %x0D / %x0D.0A
   
    "字符:换行",是指 "\r","\r\n","\n",也称"换行符".
   
    "物理行(physical_line)",是指文本显示上的行.
    "逻辑行(logical_line)",是指语法或语义上的行(也称为"段落").
   
    "软换行(soft_line)",是指在"物理行(physical_line)"行尾,使用" "或"\"
    把多个"物理行(physical_line)"合并成为一个"物理行(physical_line)",
    并忽略相邻行间的"空白".
   
    a9text的处理是基于"逻辑行(logical_line)"的.
   
2.1.3. 字符:转义(char_escape)
    char_escape = "\"
   
    a9text在大多数情况下不需要也不考虑转义,
    但为了描述a9text约定本身,有时需要使用转义.

2.2. 模式(mode)
    mode = 1*char
   
    "模式",是a9text语法上的分组,由至少一个字符组成,是组成a9text的原子单位.

2.2.1. 模式:修饰(mode_trig)
    mode_trig = "[" 1*mode_token "[" 1*char "]]"
    mode_token = "!" / "/" / "_" / "-" / "'" / "," /
                 ("%" 1*digit) / ("#" 6hexdig) / ("&" 6hexdig)
   
    "模式:修饰",实现文本的修饰功能.
    "模式:修饰"内的"物理行(physical_line)",视为"软换行(soft_line)".
    "模式:修饰"内可以包含其他"模式",包括自身.
   
    例如:
    加粗 [![文字]]
    倾斜 [/[文字]]
    下划 [_[文字]]
    删除 [-[文字]]
    上标 ['[文字]]
    下标 [,[文字]]
    前色 [#FFFFF[文字]]
    背色 [&FFFFF[文字]]
    大小 [%50[文字]]
    加粗倾斜红色50%的字 [!/#FF0000%50[文字]]
   
2.2.2. 模式:链入(mode_join)
    mode_join = "[[<=" 0*1"$" 1*char "]]"
   
    "模式:链入",可以在指定位置上导入其他文本或变量.
    "模式:链入"内的"物理行(physical_line)",视为"软换行(soft_line)".
    "模式:链入"内不可以包含其他"模式".
   
    例如:
    [[<=include.txt]] 载入的文本.
    [[<=$自定义变量]] 显示自定义变量
   
2.2.3. 模式:链出(mode_link)
    mode_link = "[[" /[^(=>)]*/ "=>" 1*char "]]"
   
    "模式:链出",可以页面跳转和显示多媒体内容.
    "模式:链出"内的"物理行(physical_line)",视为"软换行(soft_line)".
    "模式:链出"内不可以包含其他"模式".

    例如:
    [[显示名=>]]     作为锚点
    [[=>链接地址]]   以链接地址显示
    [[=>sample.png]]
    [[=>sample.swf]]
    [[=>www.trydofor.com]]
    [[=>admin@trydofor.com]]
    [[显示名=>链接地址]]

2.2.4. 模式:文本(mode_text)
    一组不满足以上"模式" 特征的连续字符,都视为"文本(mode_text)".
    "模式:文本"内不可以包含其他"模式".

2.3. 区域(area)
    area = area_head area_body area_foot
    area_head = head_blank 9*"=" area_type ":" area_info 9*"=" char_line
    area_type = /\*?[^=:\r\n]+/
    area_info = /[^\r\n]+/
    area_body = 1*char
    area_foot = head_blank 9*"=" char_line
   
    "区域",是一块特殊的文字,需要特别处理.
    例如:
    "========= *html:info =========" '*'开头表示功能性模块
    "========= text:info  ========="
    "========= java:info  ========="
    "========= html:info  ========="
    "========= des:info   ========="
   
    其中"area_type"如果以"*"开头,这表示是功能区域(不显示),否则为文本区域.
    区域不可以自包含.
    区域内的文字如何解析需要进一步定义和扩展.

2.4. 段落(para/paragraph)
    para = head_blank *(mode_text / mode_trig / mode_join /
           mode_link / char_line)
   
    "段落",是指一个"逻辑行(logical_line)",是最小的处理单元.
    由行首"空白(char_blank)",各种"模式(mode)"构成和"换行(char_line)"组成.
    "段落"内不可以内嵌其他"段落".
   
2.4.1. 段落:空行(para_blank)
    para_blank = head_blank char_line
   
    "段落:空行",是一种特殊的"段落(para)",自成一段,结束上段,开启下段,
    但不属于上下任何一段.
   
2.4.2. 段落:横线(para_line)
    para_line = head_blank 1*(9*"-" / 9*"=" / 9*"#" ) char_line
   
    "段落:横线",完全类似于"空行(para_blank)",不同的是,他会画一条水平线.
    "-","=","#" 代表着线的宽度,分别为,1,2,4个宽度

2.5. 字典(dict)
    dict = head_blank dict_key *char_blank "::" para
    dict_key   = /[^(::)\r\n]+/
   
    "字典",由行首"空白(char_blank)","::"和"段落(para)"组成.
    用来定义用户变量和说明,可以在"模式:链入(mode_join)"中引用.
   
    "字典"内只能有一个"段落(para)",不可以包含"字典".
   
    "字典键(dict_key)",是不含首尾"空白"的连续字符串.
    "键"必须和"::"在同一"物理行(physical_line)",
    "值"可以不在同一"物理行(physical_line)".
   
    "字典"的转义,只需使用"\::"来代替"::"即可.
   
2.6. 列表(list)
    list = head_blank (list_item / list_step) *char_blank ")" (para / lsit)
    list_item = "*"
    list_step = /[0-9a-zA-Z]/ *("-" /[0-9a-zA-Z]/)
   
    "列表",由行首"空白",列表类型,")"和"段落(para)"组成.
   
    "列表"内只能有一个"段落(para)",可以包含其他"列表".
   
    一组连续的列表,"缩进量(indent)"相同的列表视为同一组.
    "缩进量(indent)"的多少,体现列表间的包含关系(少的包含多的).
   
    "列表" 细分为 "列表:条目(list_item)" 和 "列表:步骤(list_step)"
   
    "列表:条目(list_item)" 是无序列表.
    "列表:步骤(list_step)" 是有序列表,可以使用"a-1","a-2"这样的组合.
   
2.7. 章节(sect/section)
    sect = /^/ sect_level sect_title char_line sect_text
    sect_level = 1*(digit ".")
    sect_title = /[^\r\n]+/
    sect_text  = 1*(area / list / dict / para)
   
    "章节",内可包含之前所以"约定","章节"内不可包含"章节".
    "章节"不可以有前置"空白".

2.8. 根(root)
    root = 1*(area / list / dict / para / sect)
   
    "根",是a9text的最高约定,领起其他约定,是一个a9text的开始.
    一个a9text中"根(root)"只能有一个,可以包含任何其他"约定".

3. 区域扩展
   "区域(area)" 的内容是需要进一步定义的.a9text预定义了如下简单"区域(area)".

3.1. 区域:文本
    "区域:文本"内的文本,不做任何解析,保留原样显示.
    格式如下:
    "========= text:info ========="
  
3.2. 区域:加密(area_secret)
    "区域:加密"内的文本是加密的密文(des算法).
    格式如下:
    "========= secret:des,info ========="

3.3. 区域:表格
    "区域:表格",实现最粗糙的表格.
    格式如下:
   
    "========= table:表格名 ========="
    ! r1-c1 | r1-c2! r1-c3|
    +--------------------------------
    |r2-c1  |r2-c2 |r2-c3 |
    +--------------------------------
    ||  r3-c1&2    |+ r3&4-c3 |
    +--------------------------------
    |r4-c1 | r4-c2 |+ r4&4-c3 |
    "================================"
   
    '!'表示加粗,'|'表一般显示,r1-c1,r1-c3加粗显示
    空格表对齐:r1-c1中对齐,r1-c2右对齐,r1-c3左对齐,默认左对齐.
    连续'|'为列合并,左起
    '|+'为行合并,上起

3.4. 区域:*HTML
    "区域:*HTML",内的文本,做为html代码使用.
    格式如下:
    "========= *html: info ========="

4. 约定图谱

4.1. 约定包含图
 
   root
    |
    +--------------------------------------------- sect
    |                                               |
    +---------------------------------- dict        +-- area
    |                                    |          |
    +------------------------ list       +-- para   +-- list
    |                          |                    |
    +------------ para         +-- list             +-- dict
    |              |           |                    |
    +-- area       +-- mode    +-- para             +-- para
    |    |              |
    |    +-- char       +-- mode_trig
    |                   |
    |                   +-- mode_join
    |                   |
    |                   +-- mode_link
    |                   |
    |                   +-- mode_text
   
    在a9text的约定中,除了"区域(area)"和"模式(mode)"直接与"字符(char)"包含外,
    其他约定都是以"段落(para)"为最小处理单元.
   
4.2. 约定结构图

    a9text = root
    root = 1*(sect / dict / list / para / area)
    sect = 1*(dict / list / para / area)
    dict = para
    list = 1*(list / para)
   
    一个a9text有且只有一个"根(root)"构成.
    "根(root)"中至少包含(无序)(sect/dict/list/para/area)中的一个.
    "章节(sect)"中至少包含(无序)(dict/list/para/area)中的一个.
    "字典(dict)"中必须包含一个para.
    "列表(list)"中至少包含(无序)(list/para)中的一个.
   
    "段落(para)"中至少包含一个"模式(mode)".
    "模式(mode)"中至少包含一个字符.
    "区域(area)"中至少包含一个字符.

5. 文本处理

5.1. 段落

    "段落(para)"在语法上讲,就是一个"逻辑行(logical_line)".而a9text是基于
    "逻辑行(logical_line)"的,因此"段落(para)"是a9text的最小处理单元.
   
    除了"区域(area)"是自定义解析规则外,段落划分遵循这样的原则,即:
    1) 一个"物理行"就是视为一个"逻辑行",也就是"段落(para)".
    2) "软换行"可以把多个"物理行"连接成一个"物理行".
    3) 除"模式:文本"外的"模式"内部的"物理行",自动视为"软换行".
   
5.2. 空白
   
    为了统一和方便,a9text中的"空白"都会转换成"半角空格"处理,
    "全角空格"等效于2个"半角空格","水平制表符"等效于4个"半角空格".
   
    "软换行",会自动去掉相邻"物理行"间的"空白".

5.3. 缩进
   
    "物理行"行首"空白"的等效"半角空格"数,称作"缩进量",用来表示层次或缩进.
   
    "区域"的缩进,表示位置.
    "段落"的缩进,表示段落的位置.
    "列表"的缩进,即表示位置,也表示层次.
    "字典"的缩进,表示位置.
    "章节"和"跟",没有缩进.

经过反复琢磨,敲定了3.1版,可以进一步编码了.
论坛页面对空格的处理不是很理想,因此版式出现了变形.对a9text和a9engine关注的同学,请到http://a9engine.sf.net
同步cvs最新版.
希望大家多提宝贵建议和意见和分享经验.