doc/UM.txt.zh_CN/doc.txt

   1
   2 @ term.shlib
   3     stdio是程序字符串信息输入输出的函数集合，dbgout用于调试信息字符串，term是以终端为显示输出的函数集合。
   4     字符串数据的输出是一个数据流，而终端信息的输出是在一个具有x/y尺寸的显示区域内的字符串输出。不同于stdio的是，它的终端尺寸和位置信息的读取和设置，以及ESC扩展指令集的使用(这里只包含了彩色显示等功能)。
   5
   6 彩色字符
   7     终端中运行字符以16种颜色进行显示，以及16种背景色进行设置。还包括常用的粗体，斜体，下划线，闪烁，反色等功能。
   8     在命令行可使用tput程序，在shlib中，将各种ESC字符命令存放到环境变量中。使用时可以比较容易地嵌入到需要显示的字符串中。
   9
  10
  11 终端尺寸大小
  12     终端是一个字符显示矩阵，具有宽度或colum列数和行数。
  13
  14     终端的大小包括shell程序的终端大小和实际终端设备的终端大小。对于显示器上的tty终端，两者是等同的。但对于图形界面中的虚拟终端，以及ssh/serial等终端软件环境下，两者是不同的。所以终端大小的设置包含两组函数。
  15
  16
  17 光标位置
  18     光标的移动，用于显示。
  19
  20
  21     但实际应用中，通常只对当前行进行光标的移动。并使用一些常用显示效果的函数。
  22
  23 disp_in_a_line()
  24 progress_bar()
  25
  26     而一些更复杂的显示，例如窗体，对话框等，使用whiptail/dialog等程序，或是相关的封装函数。
  27
  28 @ args.shlib
  29
  30 概念
  31     提到参数，让人想到命令行参数，或函数的参数。其实一些功能称呼相同或相近，但有一些略微的区别，这里罗列了一些概念名称，以及笔者对这些概念的理解。
  32 @ paramter参数，通用意义上的参数。通常是指函数中的参数，且表示一个value属性的参数。例如c语言中的函数参数，或命令行中-f file中-f之后的字符串数据的参数。
  33 @ option选项，在命令行中经常会使用option这个词，也通常用于表示-a，-b这类命令行参数。
  34 @ args参数，通常指一个程序的参数，而非一个函数的参数。
  35
  36 简介
  37     在shell编程中，包含getopt和getopts两个程序。用于不同程度的命令行参数处理。一些程序使用这两个函数可以简洁地使用命令行参数。
  38     在参数处理的代码编写时，会遇到这些问题：
  39 @ 参数的名称，注释，功能代码三者不同步，或不直观。编写了注释，
  40 @ 参数有不同的用途和分类，也有相同的程序代码。通常使用复制粘帖来实现相同的功能。例如-f <file>用于指定一个文件名字符串参数，-c <cfg> 用于指定一个配置文件的名称字符串。
  41 @ 多个参数的option helper中，文字的格式对齐。
  42
  43     args功能模块，提供了这些功能特性：
  44 @ 将命令行参数相关的信息，在一行字符串中进行描述。包括：-短参数选项，--长参数选项，subcmd参数选项，以及对应的paramter参数，当前参数名称字符串，参数对应的响应函数，参数的字符串描述信息。
  45 @ -a参数直接关联到对应的选项开关，选项参数，处理函数，程序访问这些变量和函数即可。既简化代码，也使程序更直观。
  46 @ 参数描述字符串中，以<>表示必须添加的参数，以[]表示可选的参数。
  47 @ 自动输出<程序名称>_helper字符串环境变量，用于option helper的显示。多个参数描述信息对应多个helper，可组合显示。
  48 @ 一个程序调用另一个使用args.shlib的程序时，xxx_helper可复用，无需重新编写程序。
  49 @ helper的输出进行列对齐，并可根据终端显示宽度自动调整。
  50
  51     getshopt对于一个选项对应一个处理函数的功能比较适合，对于多个参数组合使用时，args可简化参数解析的代码，并且使代码看上去比较直观。
  52
  53 使用例子
  54     args功能模块的函数较少，而是对于参数应用的各种类型的使用。
  55
  56 xxx_args_desc="
  57 param -a --all ---all <> !<pname_all> !<pproc_all> !'all files'
  58 param -f --file --- [file] !<pname_file> !<> !'specify a file.'
  59 "
  60
  61 @ scripttest
  62     在脚本程序开发时，经常需要在文件末尾调用一个测试函数，用于对函数的各种测试。将这部分代码放入另一个sh文件，使得开发时的一些测试代码保存到参数脚本。在编写单元参数和功能验证测试时，可重复使用这些测试代码。
  63     scripttest是一个测试例子程序的批量运行程序。在程序的这些时候使用：
  64 @ 一个软件包发布前的测试，一个软件包下载后使用之前的测试，称之为功能验证测试。
  65 @ 一个功能模块部分代码修改，需要测试验证主要功能模块的功能是否仍然是可用的。避免部分代码修改后其它功能运行的异常。
  66 @ 开发时以测试驱动开发。先编写测试代码，功能开发根据测试代码验证功能模块的实现。测试时对指定功能模块的catalog的id编号范围进行测试，测试好一项功能，rollup测试下一项。
  67 @ c语言之类的编译型程序的测试脚本的组织。
  68
  69 功能验证测试
  70     通常在软件开发后，版本发布之前，需要验证基本的功能是否正常使用。为了减少重复的手工操作，以脚本的形式对程序进行测试。
  71
  72 scripttest
  73
  74     默认对软件包的所有测试项进行测试。如果遇到failed项，使用-r参数忽略参数failed进行测试，测试会显示failed项。
  75     每个测试项的测试脚本运行时间超过5秒时，都会显示所需运行时间。当测试一直运行在某一个测试项时，用于参考测试是否运行异常。
  76
  77 单元测试
  78     在新的功能模块的开发中，一些时候先根据使用编写测试代码，并在多个参数项的测试脚本中编写。
  79
  80 scripttest -S -b 1.1 -e 1.5
  81 scripttest
  82
  83     先设置测试的起止范围为1.1-1.5的测试项，并保存设置。在运行scripttest测试时，只对指定的id范围进行参数。
  84     在新编写的功能模块，测试脚本是对功能模块不同的使用方法的记录和组织。
  85     scripttest判断程序是否测试ok，是将当前测试程序的输出，与开发时认为正确的stdout字符串信息进行比较。所以在功能模块代码编写和测试时，需要以stdout的输出为测试合格的依据。通常输出功能success或failed等字符串，代替一个每次运行测试时都不相同的数值。例如电压值在3.0~3.6v范围内的为正常供电电压，使用一个if语句判断后输出voltage ok，在这个电压范围之外的值，输出voltage error。scripttest运行时，与保存在测试例子中的标准输出信息比较。而如果输出
  86     当编写并测试好一个测试项时，rollup测试id。
  87
  88 scripttest -R
  89
  90     再测试时，从1.2测试项运行测试脚本。逐项测试，直到1.x这个功能模块测试完毕，再程序设置起止范围，进行功能验证测试。
  91
  92 scripttest -S -b 1.1 -e 1.5
  93 scripttest
  94
  95     当测试中功能failed，scripttest会显示当前测试输出信息与正确的测试输出信息的diff比较内容。开发者根据测试脚本的输出内容，判断程序的异常。
  96
  97 代码修改验证测试
  98     一个功能模块的代码进行修改后，需要验证修改的代码是否影响原有的代码功能。
  99
 100 scripttest -S -b 1.1 -e 1.5
 101 scripttest
 102
 103     与单元测试的验证一样，对一个模块进行单元测试。
 104
 105 程序测试脚本集合
 106
 107
 108 @ attr属性
 109     shell环境下，环境变量的一个不足是只能使用单个变量和一维数组，对于结构体类型的数据形式不能使用。
 110     attr使用__连接变量和成员变量之间，进行结构化的数据访问。变量名称字符串的冗长，来实现一个变量下的成员变量。
 111     虽然名称字符串长度可以比较长，但较多变量时，较长的变量名称，使程序占用内存资源较多，且在名称遍历时是对所以环境变量进行遍历，较长的字符串相对较费cpu，所以变量的下的成员变量级数不适合太多。通常以module::section::attr这样的结构对成员变量进行组织。
 112     在使用attr的程序中，通常还包含module__list，用于表示module下的成员变量列表。这使一个结构化的变量可以根据广度和深度进行遍历。
 113
 114
 115 @ 格式化字符串输出与解析
 116     shell本身包含较多字符串使用功能，包括字符串的截取，追加，查找，替换，大小写变换，正则匹配等。而在shlib中，将程序中用到的字符串相关功能罗列如下：
 117 @ evaln，evlstrn等循环解析$环境变量。
 118 @ strfmt，对字符串中@变量进行格式化的字符串stream输出。
 119 @ strsyntax，对字符串以分隔符分隔解析成若干组字符串，或以正则表达式匹配对应的字符串数组。与strfmt是两个对称的功能，实现字符串与变量之间的转换。
 120
 121 @ catalog目录功能
 122     catalog是目录的意思，它包含这些内容：
 123 @ cataid，以"."连接的纯数字目录id编号。
 124 @ catadir，目录结构在文件系统中的体现。
 125 @ catalog，以tab缩进为目录结构表示的文件结构。在目录的单行字符串中，以一种字符串格式描述信息。既可用于文档编写，又可根据格式解析的内容，用于程序的某些功能。
 126
 127 @ imi文件
 128
 129 @ 模板文件
 130
 131 @ 程序设计和代码自动的同步输出
 132     程序的设计，可以是xml文件组成的uml设计文件，也可以是catalog结构的文本文件。
 133     codegen将设计文件解析后输出attr属性变量，根据属性变量输出程序目录/文件/代码。
 134     程序的目录和文件是通用的输出。不同的源码类型，使用不同的模板类型，输出对应的代码。
 135
 136
 137 @
 138
 139
 140
 141