first version.

[build-srcpkg.git] / res / Style / TmplParam / PB1.0 / src-mdl-obj-tmpl / src-c-tmpl.imi

#!/bin/imi -t
############################################################
# source: src-c-tmpl.imi
# author: devenkong(18151155@qq.com)
# date: 2022-05-28
############################################################
# note:
#     c语言.c源码模板文件。
############################################################

#
# todo：
# @ @{*section}调用某个section的定义，或以@(section name)调用。
# @ 一些文字内容添加_$LANG的sfx，以不同的语言输出文件内容。
# @ 
# @ 
#


#
# code-operation
# @ codegen，根据catalog输出.c、.h文件，已输出的代码文件使用codesync同步更新。
# @ codesync，将catalog和代码框架进行同步更新。
# @ codesrc2hdr，将src文件的内容更新到.h文件。
# 
#

#
#     程序的模板，对应着程序的编码风格和模块化的程序设计。
#     使用comment-tag，将程序划分成不同功能和用途的代码区域，便于使用非lex-gmr的程序解析代码。
#     程序中的inc、pub_var、pub_func，表示头文件包含、exported变量和函数，是一个程序设计时的
# 主要元素，在catalog中以tabed-txt文档记录，便于输出程序代码框架，简化开发。
#     而头文件中包含inc、pub_define、pub_var、pub_func。在输出.c/.cpp源文件的同时，根据.h的
# tmpl输出.h文件。
#     程序中的.h文件可根据.c/cpp文件的内容输出，一些内容只需在.c或.cpp文件中编写一次，同步内容到
# 其它文件。程序编译成lib之后，只有lib文件和.h文件，一些源码中函数说明的注释在.h文件中添加，便于
# 开发时参考使用。使用codesrc2hdr，只需在源代码文件编写函数，即可更新到.h文件。
#     
#
#

#
# @ imi文件以模块/imi文件、section、属性来组织和存储数据。
# @ 通常一个imi中包含相对较多个section，而一个section中包含少量的属性，imi使用于这类数据存储。
# @ 在一些使用场合，以包含一些属性/变量的定义为主，例如一个config文件，又包含少量与config无关的
#   参数用于一些应用，这时imi和win下的ini文件的功能类似。
# @ 与imi类似的LISP，以()包含和表示结构化的数据，以及数据的处理。但imi只用于数据的存储，和一些
#   应用场合的数据的表达，其中的功能函数的定义和section的调用，用于简化数据的组织和使用，不用于
#   程序处理。程序的编写在c程序，以及shell-script中编写。
# @ 
# 
# 



#
# 
# @ 文件以setting为imi的设置section，以文件名同名的templete为main-section，
# @ 在templete中定义一个src文件包含的各个section。这些section在templete之下的section中定义。
# @ templete在文本编辑器中可对不同的section进行编辑，这样编辑时仍可以一个src文件进行编辑。
# @ templete以及其中定义的section中用到的属性变量，一些在当前文件中定义，一些在其它文件中定义，
#   在其它文件中定义的属性变量，保存到templete的external属性中。在运行templete时，external中的
#   属性未定义时，根据程序的设置，可输出异常提示信息。
# @ templete的section之间包含blank-lines，用于代码格式的美观，并可使用编辑器的设置项设置各类section
#   之间的blank-lines。
# @ 一些section的内容较固定，而一些程序feature的定义根据其它imi中的section的定义，添加到列表中的，
#   这类section称之为列表section。列表section的feature-item之间包含blank-lines，可设置。
# @ templete文件中需要使用不同位置的blank-lines，在blankLines这个section中定义，包含name和value。
#   属性名称以bl为pfx，在使用时以"${blFeatureSection}"使用，表示代码中各个section之间的blank-lines。
# @
# 

# 
# @ tmpl文件使用一个example，以<tag>标签标识一个src中的element，将tag标签的内容当一个src的feature的example，
#   用于输出src-XXX-lang-feature.imi中的feature的格式。同时输出一个imi文件，使用该src-XXX-lang-feature.imi
#   文件输出的src-code与example相同，用于imi的test。
# @  
# 
# 
# 


#
# note:
# @ 在当前ini配置文件定义public-param，例如文件hdr分隔符字符串，没行注释的prefix。
# @ code-block=param-block + templete-block。解析另一个ini"代码模块描述文件"时，
#   source运行param-block，添加这些环境变量，并进行设置。再source运行templete-block的block模板，
#   对应的环境变量中保存了这个code-block的代码。这样，根据templete和"代码模块描述文件"，生成了一个
#   block的代码。
# @ 一个源文件由多个block组成，各个block填充后，生成source-code。
# @ 以一份sample-code，从code中copy字符串，设置public-param，来生成一种src-file的ini描述文件。
#   生成ini文件时，指定另一个参考ini文件，程序根据参考ini文件，获取section、var、function的
#   内容，用于在ui上由用户进行重新设置，一些固定的值从sample-code中截取，一些非固定的值编写代码
#   生成函数。
# @ "代码模块描述文件"根据当前ini配置生成参数列表，由用户填充参数信息。该文件可以和xml文件转换，
#   以便于其它使用xml格式保存数据的程序，来编辑和设置参数。
# @ 在code-syntaxer时，不以source运行一个section。以section对应的文本解析函数进行解析。
#   所以一种源文件格式，对应一个ini"源文件格式描述文件"，和对应的代码处理函数的shlib。用于使用
#   "代码模块描述文件"生成源代码、code-syntaxer、code-comment-doc、code-info-getting。
# @ 对已有的src-file的某个block进行解析，逐个block调整代码，使得代码的格式可使用命令行程序进行
#   解析。
# @ 常用的file-hdr、inclist、namelist、symbollist、varlist、funclist、func-comment作为
#   通用的功能。
# @ 定义源文件的词法和语法，用于已有代码的解析。
#
#
# @ 一些已定义的源文件描述文件，以及某种code-style对应的配置文件等资源，可使用命令行程序，将资源
#   文件放置到存储空间，使用者可使用命令行程序浏览到各种已定义的文件，并可像pkg软件一样使用这些
#   配置文件。
#
# @ pkg-configer、pkg-builder、prj-builder、mod-builder
# @ tagdoc、code-syntaxer、scripttest、*xxx*unit
#


#
# 代码格式设置的参数文件
# "#"，"//"，"/*"，"*/"，表示注释
# []，表示一个section，section名称字符串以"-"连接单词，与括号之间插入一个空格。
# 变量的定义与shell-script相同，名称的单词之间以"_"连接。
# <>表示目录结构的id
# ""，''，表示一个字符串，包括"和'字符。
# ()表示一个数组，并且可多行显示。
# {}表示一个结构体描述，用于dstruct/dvar的结构化数据的赋值。
# =表示tag和value字符串的对应关系，通常是一个属性的赋值操作。
# +=表示字符串的累加，等同于shell中的+=
# 

# 
# [ <module>::<type>::<name> ]
# [ <type>::<name> ]
# [ <name> ]
# global var=abc
# strfmt(eEt) tmpl_str_fmt="@{var}"
# strfmt tmpl_str_fmt="@{var}"
# var2=aaa
# var2+=bbb
# [ setting ]
# DEFAULT_ATTR_PROC="global"
# eval IMINAME_FMT="${IMIFILE%.*}"
# STRFMT_EVALN="eval"
# STRFMT_TRANS="e"
# 








[ setting ]
DEFAULT_ATTR_PROC="global"
eval IMINAME_FMT="${IMIFILE%.*}"
STRFMT_EVALN="eval"
STRFMT_TRANS="e"

loadimi file="shlib-lite/c-lang/c-lang-feature.imi"
DEFAULT_ATTR_PROC="attr"


[ templete ]


#
# 一些环境变量，用于templete的参数，在当前文件load之前定义。
#
# 定义编程语言类型，用于itemlist使用的tmpl的编程语言作用域pfx
LANG=C
# section之间的空行数
section_blanks_cnt=3

#
# comment elements
# 使用注释元素，使不同编程语言使用相同的comment-templete。
#
cmt2_begin="/*"                # block注释的begin符号组合
cmt2_end="*/"                  # block注释的end符号组合
cmt_blank=" "                  # 在block注释的begin和end行之间的注释，行首的空格符号。
cmt_pfx="*"                    # 在block注释的begin和end行之间的注释，行首的空格符号之后的符号，不包含一个空格。
cmt_bar_fmt="$(rptstr * @{1})" # 在block注释的begin和end行之间的注释中，用于划分code区域，使程序根据注释长条，
                               # 划分为不同的区域。
                                                           # section-seperator以30个符号的bar进行分隔
                                                           # 函数体以50个符号的bar进行分隔
                                                           # 文件hdr使用80个符号的bar进行分隔
#******************************
#**************************************************
#********************************************************************************


section_blanks_fmt='@(rptstr "
" $section_blanks_cnt)'
# 一个sectionhdr包含两个表示section的comment，一个是cmt_stub，简短，用于code partition，
# 一个内容较长，用于humen-readable-section，代码更美观。
section="@{cmt2_begin} <section:@{1}> @{cmt2_end}
@{cmt2_begin}@{cmt_bar 30}
@{cmt_blank}@{cmt_pfx} Section @{1}
@{cmt_blank}@{cmt_bar 30}@{cmt2_end}"


#
# 用于itemlist的templete
# 包括：inc、var、func
#
inc="#include <@{1}.@{2}> # ${3}"
pub_var="@{CMT::var::syntax}
@{$LANG::var::syntax}"
pub_func="@{CMT::func::syntax}
@{$LANG::func::syntax}"

#
# 各个section的tmpl
# itemlist根据catalog或imi中curr_<xxx>_list的定义，在运行时输出内容。
#
file_hdr="@{cmt2_begin}@{cmt_bar 80}
@{cmt_blank}@{cmt_pfx} Section @{1}
@{cmt_blank}@{cmt_bar 80}@{cmt2_end}"
inc_list="
@(itemlist inc)

"
# private的定义在编码时使用，不使用itemlist
pri_var_typedef="
@{cmt2_begin}@{cmt_bar 50}
@{cmt_blank}@{cmt_pfx} TODO: Replace private var & typedef code here.
@{cmt_blank}@{cmt_bar 50}@{cmt2_end}
"
pub_var_list="
@(itemlist pub_var)

"
pri_func="
@{cmt2_begin}@{cmt_bar 50}
@{cmt_blank}@{cmt_pfx} TODO: Replace private function code here.
@{cmt_blank}@{cmt_bar 50}@{cmt2_end}
"
pub_func_list="
@(itemlist pub_func)

"

#
# c-src文件包含几个section的组合，
#
syntax[section_src_hdr]="@{section file_hdr}"
syntax[file_hdr]="@{file_hdr}"
syntax[section_inc]="@{section inc}"
syntax[inc_list]="@{inc_list}"
syntax[section_pri_var_typedef]="@{section pri_var_typedef}"
syntax[pri_var_typedef]="@{pri_var_typedef}"
syntax[section_pub_var]="@{section pub_var}"
syntax[pub_var_list]="@{pub_var_list}"
syntax[section_pri_func]="@{section pri_func}"
syntax[pri_func]="@{pri_func}"
syntax[section_pub_func]="@{section pub_func}"
syntax[pub_func_list]="@{pub_func_list}"
syntax[section_end_code]="@{section end_code}"

syntax="@{syntax[section_src_hdr]}
@{syntax[src_hdr]}
@{section_blanks}
@{syntax[section_inc]}
@{syntax[inc_list]}
@{section_blanks}
@{syntax[section_pri_var_typedef]}
@{syntax[pri_var_typedef]}
@{section_blanks}
@{syntax[section_pub_var]}
@{syntax[pub_var_list]}
@{section_blanks}
@{syntax[section_pri_func]}
@{syntax[pri_func]}
@{section_blanks}
@{syntax[section_pub_func]}
@{syntax[pub_func_list]}
@{section_blanks}
@{syntax[section_end_code]}
@{section_blanks}"