caset 1.0.0

data/lib/casetdown/casetter.rb

@@ -0,0 +1,141 @@
+#coding:utf-8
+
+#------------------------------------------------------------------------------
+# Markdown 解析器加载与包装器
+#------------------------------------------------------------------------------
+module CasetDown
+  module_function
+
+  # casetdown 库根目录（lib/）。
+  #
+  # 供代码执行引擎以 `ruby -I"..." ./~tmp.rb` 启动子进程时定位
+  # require "casetdown"，使仓库直跑与 gem 安装两种方式下，
+  # 执行脚本中的 EnData / SimTab / TinText 数据绑定均可用。
+  #
+  # @return [String] lib 目录的绝对路径
+  def home
+    File.expand_path('..', __dir__)
+  end
+
+  # Loader
+  # 加载指定 Markdown 文件并解析为结构化数据。
+  #
+  # @param path [String] Markdown 文件路径
+  # @param option [Hash] 可选参数，会合并到解析参数中
+  # @option option [Class] :parser 解析器类，默认为 ReDiscount（manticore）
+  # @option option [Boolean] :doc 是否返回原始文档对象，默认为 true
+  # @option option [Boolean] :tree 是否返回树结构，默认为 true
+  # @option option [Boolean] :src 是否返回源节点列表，默认为 true
+  # @return [Hash] 解析结果，包含 :path, :src, :tree, :doc 等键
+  # @example
+  #   result = CasetDown.load("README.md")
+  #   result[:doc].text  # 获取原始文本
+  def load path, option={}
+    args = {path: path}.merge(option)
+    text = (File.read path).gsub("\r","").split("\n").map{|line|line.rstrip}.join("\n")
+    return self.parse(text, args)
+  end
+
+  # InlineStructs
+  # 将 Markdown 文本字符串解析为结构化数据。
+  #
+  # @param text [String] Markdown 原始文本
+  # @param option [Hash] 可选参数
+  # @option option [Class] :parser 解析器类，默认为 RDiscount
+  # @option option [Boolean] :doc 是否返回原始文档对象，默认为 true
+  # @option option [Boolean] :tree 是否返回树结构，默认为 true
+  # @option option [Boolean] :src 是否返回源节点列表，默认为 true
+  # @option option [String] :path 文件路径标识，默认为 'tmp'
+  # @return [Hash] 解析结果
+  #   - :path [String] 文件路径
+  #   - :src [Script] 原始节点列表包装器
+  #   - :tree [Tree] 按标签分组的节点树
+  #   - :doc [RDiscount] 原始文档对象
+  def parse text, option={}
+    args = {
+      parser: ReDiscount, # parser := {Kramdown::Document | RDiscount} ★ Kramdown::Document无法处理好多重空行问题
+      doc: true,
+      tree: true,
+      src: true,
+      path: 'tmp'
+    }.merge(option)
+    document = args[:parser].new(text)
+    html = "<html>"+document.to_html+"</html>"
+    script, tree = [],{}
+    XmlParser.parse(html).elements.each do|node|
+      doc = node.to_a
+      script << node
+      tree[doc[0]] ||= []
+      tree[doc[0]] << node
+    end
+    result = {path: args[:path]}
+    result[:src]  = Script.new(native: script) if args[:src]
+    result[:tree] = Tree.new(native: tree)     if args[:tree]
+    result[:doc]  = document                   if args[:doc]
+    return result
+  end
+  
+  # 文档树结构包装器，按标签名分组存储 DOM 节点。
+  #
+  # 内部使用 @content 存储分组后的节点树，键为标签名，值为节点数组。
+  class Tree
+    # 初始化树结构。
+    #
+    # @param options [Hash] 初始化参数
+    # @option options [Hash] :native 原生树结构数据
+    # @option options [String] :json JSON 字符串，会解析为树结构
+    # @option options [String] :path 文件路径，通过 CasetDown.load 获取
+    # @option options [String] :doc Markdown 文本，通过 CasetDown.parse 获取
+    # @return [Tree] 树实例
+    def initialize options={}
+      @content ||= options[:native]
+      @content ||= JSON.parse(options[:json]) if options[:json]
+      @content ||= CasetDown.load(options[:path])[-1] if options[:path]
+      @content ||= CasetDown.parse(options[:doc])[-1] if options[:doc]
+      @content ||= {}
+    end
+    
+    # 遍历并返回树内容，支持传入回调函数。
+    #
+    # @yield [content] 传入树内容，缺省返回内容本身
+    # @yieldparam content [Hash] 树结构数据
+    # @yieldreturn [Object] 回调处理结果
+    # @return [Object] 执行 block.call(@content) 的结果
+    def nodes &block
+      block = lambda{|content|content} unless block
+      block.call(@content)
+    end
+  end
+  
+  # 文档节点顺序列表包装器，保持原始文档的节点顺序。
+  #
+  # 内部使用 @content 存储原始节点数组。
+  class Script
+    # 初始化节点列表。
+    #
+    # @param options [Hash] 初始化参数
+    # @option options [Array] :native 原生节点数组
+    # @option options [String] :json JSON 字符串，会解析为节点数组
+    # @option options [String] :path 文件路径，通过 CasetDown.load 获取
+    # @option options [String] :doc Markdown 文本，通过 CasetDown.parse 获取
+    # @return [Script] 脚本实例
+    def initialize options={}
+      @content ||= options[:native]
+      @content ||= JSON.parse(options[:json]) if options[:json]
+      @content ||= CasetDown.load(options[:path])[0] if options[:path]
+      @content ||= CasetDown.parse(options[:doc])[0] if options[:doc]
+      @content ||= []
+    end
+
+    # 遍历并返回节点列表，支持传入回调函数。
+    #
+    # @yield [content] 传入节点数组，缺省返回内容本身
+    # @yieldparam content [Array] 节点数组
+    # @yieldreturn [Object] 回调处理结果
+    # @return [Object] 执行 block.call(@content) 的结果
+    def stack &block
+      block = lambda{|content|content} unless block
+      block.call(@content)
+    end
+  end
+end

data/lib/casetdown/cli.rb

@@ -0,0 +1,129 @@
+#coding:utf-8
+
+#------------------------------------------------------------------------------
+# cm 命令实现（CasetDown::CLI）
+#------------------------------------------------------------------------------
+# 对可执行 Markdown 文档做形式化执行与生成：
+#   解析文档结构 -> 导入导出表格 -> 执行代码块 -> 结果回写渲染文件
+#
+# 命令行用法（bin/cm 薄启动器调用 CasetDown::CLI.run）：
+#
+#   cm [options] <filename>[.md]
+#
+#   options:
+#   --help     查看帮助
+#   --check    检查文档结构
+#   --source   查看文档中的源代码
+#   --rtab     导入外部表格到文档中
+#   --wtab     导出内部表格到外部文件
+#   --input    导出源代码文件并渲染文档
+#   --output   导出代码运行结果
+#   --all      导出源代码和运行结果(input+output)
+#   --preview  预览渲染文档(不生成渲染结果)
+#   --debug    调试开关, 不删除中间代码
+#   --rendfile 渲染文档并生成一个时间戳(默认)
+#------------------------------------------------------------------------------
+module CasetDown
+  module CLI
+    module_function
+
+    # CLI 帮助文本。
+    #
+    # @return [String] 多行帮助信息
+    def help
+      %Q{cm [options] <filename>[.md]
+
+  options:
+  --help     查看帮助
+  --check    检查文档结构
+  --source   查看文档中的源代码
+  --rtab     导入外部表格到文档中
+  --wtab     导出内部表格到外部文件
+  --input    导出源代码文件并渲染文档
+  --output   导出代码运行结果
+  --all      导出源代码和运行结果(input+output)
+  --preview  预览渲染文档(不生成渲染结果)
+  --debug    调试开关, 不删除中间代码
+  --rendfile 渲染文档并生成一个时间戳(默认)
+}
+    end
+
+    # 命令行入口：解析参数并执行对应动作。
+    #
+    # @param argv [Array<String>] 命令行参数（不含程序名）
+    # @return [Integer] 进程退出码
+    def run argv
+      pool = argv.dup
+      check, source = false, false
+
+      if pool.include?('-h') or pool.include?('--help')
+        puts help
+        return 0
+      end
+
+      if pool.include?('--check')
+        check = true
+        pool.delete '--check'
+      end
+      if pool.include?('--source')
+        source = true
+        pool.delete '--source'
+      end
+
+      table, file = [], []
+      ['--rtab','--wtab'].each do|tag|
+        if pool.include?(tag)
+          table << tag
+          pool.delete tag
+        end
+      end
+      ['--input','--output','--all','--preview','--debug'].each do|tag|
+        if pool.include?(tag)
+          file << tag
+          pool.delete tag
+        end
+      end
+
+      path = pool.last
+      path = Dir["./*.md"].last unless path
+      return 0 unless path
+
+      if File.exist?(path)
+        cds = CasetDown.load path
+      elsif File.exist?("#{path}.md")
+        cds = CasetDown.load "#{path}.md"
+      else
+        puts "File #{path} not exist."
+        return 1
+      end
+
+      if check
+        puts "checking>>>>"
+        pp CasetDown::Check.all(cds)
+        return 0
+      end
+      if source
+        puts "source>>>>"
+        pp CasetDown.search_codes(cds)
+        return 0
+      end
+
+      render_file cds, table: table.map{|i|i[2..-1].to_sym}, file: file.map{|i|i[2..-1].to_sym}+[:rendfile]
+      return 0
+    end
+
+    # 默认渲染流程：表格导入导出 + 代码执行 + 渲染文件生成。
+    #
+    # cm 主流程与 cml 监听渲染共用的入口。
+    #
+    # @param cds [Hash] CasetDown.load 的解析结果
+    # @param table [Array<Symbol>] 表格选项（:rtab / :wtab）
+    # @param file [Array<Symbol>] 文件选项（:input / :output / :all / :preview / :debug / :rendfile）
+    # @return [String] 回写后的完整文档文本
+    def render_file cds, table: [], file: [:rendfile]
+      tmp = CasetDown.render_table(cds, opt: table)
+      CasetDown.run_to_file cds, stream: tmp[:text], data: tmp[:data], fact: tmp[:fact], file: file
+    end
+
+  end
+end

data/lib/casetdown/live.rb

@@ -0,0 +1,102 @@
+#coding:utf-8
+require 'digest'
+require 'fileutils'
+
+#------------------------------------------------------------------------------
+# cml 命令实现（CasetDown::Live）
+#------------------------------------------------------------------------------
+# Markdown 文件监听渲染：持续监视指定目录下的 .md 文档，
+# 内容发生变更时自动执行 cm 默认渲染流程（表格 + 代码 + 渲染文件），
+# 并把最新渲染版本同步为 "<文件名>.latest.md"。
+#
+# 命令行用法（bin/cml 薄启动器调用 CasetDown::Live.run）：
+#
+#   cml              # 监视当前目录所有 .md
+#   cml <dir>        # 监视指定目录
+#   cml <dir> <glob> # 监视指定目录下匹配 glob 的文档（如 '*.md'）
+#
+# 变更检测：mtime 触发 + MD5 摘要确认（原版为 atime 触发，
+# Windows 卷常见关闭 atime 更新会导致漏检，故改用 mtime）。
+#------------------------------------------------------------------------------
+module CasetDown
+  module Live
+    module_function
+
+    # 命令行入口：解析参数并进入监听循环（正常情况下不返回）。
+    #
+    # @param argv [Array<String>] 命令行参数
+    # @return [Integer] 进程退出码（仅在参数校验失败时返回）
+    def run argv
+      if argv.empty?
+        cd = Dir.pwd
+        fs = '*'
+      else
+        cd = argv.first
+        fs = argv.size>1 ? argv.last : '*'
+        if Dir["#{cd}/#{fs}"].select{|p|p[-3..-1]=='.md'}.empty?
+          warn "No file(#{cd}/#{fs}) exist."
+          return 1
+        end
+      end
+
+      warn "DONT USE POSTFIX .latest.md, FILENAME.latest.md WONT BE UPDATED!"
+
+      table = {}
+      loop do
+        scan_once table, cd, fs
+        sleep 1
+      end
+    end
+
+    # 执行一轮扫描：登记新文件、检测内容变更并渲染。
+    #
+    # 供监听循环调用，独立暴露以便测试。
+    #
+    # @param table [Hash{String => Array}] 变更登记表
+    #   值为 [mtime, size, md5摘要] 三元组
+    # @param cd [String] 监视目录
+    # @param fs [String] 文件名匹配模式（glob）
+    # @return [Array<String>] 本轮发生变更并完成渲染的文件路径列表
+    def scan_once table, cd, fs
+      events = []
+      Dir["#{cd}/#{fs}"].each do|path|
+        next unless path[-3..-1]=='.md'
+        next if path[-10..-1]=='.latest.md'
+        unless table[path]
+          table[path] = [File.stat(path).mtime, File.stat(path).size, Digest::MD5.hexdigest(File.read(path))]
+        end
+        otime, osize, odigest = table[path]
+        mtime = File.stat(path).mtime
+        msize = File.stat(path).size
+        if mtime>otime # && (msize != osize || msize == osize)
+          adigest = Digest::MD5.hexdigest File.read(path)
+          if adigest!= odigest
+            text = render path
+            table[path] = [mtime, msize, adigest]
+            latpath = (Dir["#{path[0..-4]}.*.md"] - ["#{path[0..-4]}.latest.md"]).max
+            latest = "#{path[0..-4]}.latest.md"
+            File.delete(latest) if File.exist?(latest)
+            puts ">#{path} changed -> #{latpath || latest}(#{adigest}).";$stdout.flush
+            if latpath
+              FileUtils.copy_file(latpath, latest)
+            else
+              File.write(latest, text) # 兜底：无时间戳渲染文件时直接写入渲染文本
+            end
+            events << path
+          end
+        end
+      end
+      return events
+    end
+
+    # 渲染单个文档（等价于对该文件执行一次无参数 cm）。
+    #
+    # @param path [String] Markdown 文档路径
+    # @return [String, nil] 渲染回写后的完整文档文本
+    def render path
+      cds = CasetDown.load path
+      CasetDown::CLI.render_file cds
+    end
+
+  end
+end

data/lib/casetdown/support/api_app.rb

@@ -0,0 +1,127 @@
+#coding:utf-8
+
+##################################################################################################################
+#
+# EnData::ApiRequest —— WEBOOT API 调用应用层
+# 移植自 imdoc/EnData/api-app（依赖外部 gem webot 提供的 weboot 接口）。
+#
+# 本文件为可选加载：casetdown 入口在 require 时做了 LoadError 兜底，
+# 未安装 webot 的环境中 cm/cml 与数据绑定功能不受影响，
+# 仅 EnData::ApiRequest API 调用扩展不可用。
+#
+# API:   template1 # an example of templates
+# API:   bind      # single bind
+# API:   send      # single send
+# API:   make      # batch bind
+# API:   handle    # batch send
+# API:   run       # make + handle
+#
+# Step1: EnData::ApiRequest.make
+# CASE:  table1 × table2 × ... >--(join)--> task_table + bind_table(ref,val) >--eval(binding)--> task_instances
+# USE:   EnData.join_table() |> EnData.make_ref |> EnData.make_doc |> EnData::ApiRequest.bind
+#
+# Step2: EnData::ApiRequest.handle
+# CASE:  task_instances >--(API CALLING)--> running_results
+# USE:   EnData::ApiRequest.send
+#
+##################################################################################################################
+require 'weboot'
+
+# 便捷方法：把表名对应的数据体用分号拼接（API 命令序列）。
+#
+# @param tabname [String] 表名
+# @return [String] 分号拼接的命令串
+def cmds tabname
+  return EnData.get_body(tabname).join(";")
+end
+
+# 便捷方法：批量生成并执行 API 任务（make + handle）。
+#
+# @param tables [Array<Array>] 参与拼接的任务表
+# @param bind_table [Hash{String => String}] 引用名 => 引用文本
+# @return [Array] 执行结果列表
+def run tables, bind_table
+  EnData::ApiRequest.run tables, bind_table
+end
+
+module EnData
+  # API 请求应用层。
+  module ApiRequest
+    module_function
+
+    # 示例请求模板（bind 的缺省模板）。
+    #
+    # @return [String] 请求模板文本
+    def template1
+%Q|POST ${path} HTTP/1.1
+Host: ${server}
+Accept: */*
+Content-Type: application/json
+
+{
+  "protocol": "${protocol}",
+  "host": "${device}",
+  "user": "${access-key}",
+  "app-key": "${app-key}",
+  "cmds": "${operations}",
+  "method": "${processes}"
+}|
+    end
+
+    # 把单条绑定数据填入请求模板。
+    #
+    # @param options [Hash{String => Object}] 模板字段取值
+    # @param template [String] 请求模板，缺省 template1
+    # @return [String] 填充后的请求文本
+    def bind options, template=EnData::ApiRequest.template1
+      Replacement.init
+      ['path','server','protocol','device','access-key','app-key','operations','processes'].each do|key|
+        Replacement[key] = options[key].to_s
+      end
+      return TinText.instance(template)
+    end
+
+    # 发送单条请求并解析响应。
+    #
+    # @param context [String] 请求文本
+    # @return [Object] 响应中的 content 字段
+    def send context
+      request = Weboot.request context
+      response = Weboot.construct request
+      report = JSON.parse(response['body'])['content']
+    end
+
+    # 批量绑定：拼接任务表、替换引用、生成任务实例。
+    #
+    # @param tables [Array<Array>] 任务表列表（依次笛卡尔拼接）
+    # @param bind_table [Hash{String => String}] 引用名 => 引用文本
+    # @return [Array<String>] 任务实例列表
+    def make tables, bind_table
+      # Please don't join too much tables
+      tasks = tables.shift
+      tasks = EnData.join_table(tasks, tables.shift) until tables.empty?
+      bind_table.each{|refname, reftext|tasks = EnData.make_ref(tasks, refname, reftext)}
+      binds = EnData.make_doc(tasks)
+      instances = binds.map{|binding|EnData::ApiRequest.bind binding} # with EnData::ApiRequest::template
+    end
+
+    # 批量发送：逐条执行任务实例。
+    #
+    # @param instances [Array<String>] 任务实例列表
+    # @return [Array] 执行结果列表
+    def handle instances
+      instances.map{|instance| EnData::ApiRequest.send instance}
+    end
+
+    # make + handle 一体化执行。
+    #
+    # @param tables [Array<Array>] 任务表列表
+    # @param bind_table [Hash{String => String}] 引用名 => 引用文本
+    # @return [Array] 执行结果列表
+    def run tables, bind_table
+      instances = EnData::ApiRequest.make tables, bind_table
+      EnData::ApiRequest.handle(instances)
+    end
+
+  end
+end

data/lib/casetdown/support/endata.rb

@@ -0,0 +1,197 @@
+#coding:utf-8
+
+['yaml','json'].each{|mod|require mod}
+
+#------------------------------------------------------------------------------
+# 脚本内嵌数据整理（EnData）
+#------------------------------------------------------------------------------
+# 移植自 imdoc/EnData/endata + endata-app，为 casetdown 的代码执行通道提供
+# 数据绑定能力：表格与全局配置以 endata 格式附着在脚本 __END__ 之后，
+# 执行中的脚本通过 EnData.table('表名') 取回二维表数据。
+#
+# endata 数据段格式（位于脚本 __END__ 之后，有顺序要求）：
+#
+#   [global@endata ~]$ruby global
+#   {"配置名"=>"配置值", ...}
+#
+#   [table@endata ~]$ruby 表名
+#   [["字段1", "字段2"], ["值1", "值2"], ...]
+#
+# 行格式为 [用户@endata 路径]$解释器 名称 参数1# ...
+#   - 用户/路径：占位语义，可自由命名
+#   - 解释器：ruby / yaml / json / plaintext，决定 source 的解析方式
+#   - 名称：表的唯一标识（EnData.table 的检索键）
+#
+# 使用样例见 doc/MANUAL.md 第 5 节“数据绑定”。
+#------------------------------------------------------------------------------
+module EnData
+  extend self
+
+  # 读取当前脚本的 __END__ 数据段（DATA 常量），并做结果缓存。
+  #
+  # @note 仅在带 __END__ 段的脚本（cm 生成的执行脚本）中可用
+  # @return [String] 数据段原始文本
+  def load
+    @__EnData__ ||= DATA.read
+    return @__EnData__
+  end
+
+  # 解析 endata 数据段为 {名称 => 数据项} 哈希。
+  #
+  # 每个数据项包含：user/path/handler/name/arguments/context 七个键。
+  #
+  # @param data [String, nil] 数据段文本，缺省读取当前脚本 DATA
+  # @return [Hash{String => Hash}] 数据项列表（按名称索引）
+  # ['username'@EnData 'workpath']$ 'command' 'scriptname' 'argument1#' ...
+  def parse data=@__EnData__
+    @__datalist__ = {}
+    temp = {
+      'user' => '',
+      'path' => '',
+      'handler' => '',
+      'name' => '',
+      'arguments' => [],
+      'context' => []
+    }
+    data.split("\n").each do|line|
+      if matcher = /^\[[\w|\s]*\@endata[\w|\s|\/|\~]*\]\$/.match(line)
+        @__datalist__[temp['name']] = temp
+        front, back = line.split("@endata")
+        usr = front.sub("[",'').strip
+        pwd = back.split("]")[0].strip
+        cmd = back.split("]$")[-1].split(" ")
+        handler, name, arguments = cmd[0], cmd[1], cmd[2..-1]
+        context = ''
+        temp = {
+          'user' => usr,
+          'path' => pwd,
+          'handler' => handler,
+          'name' => name,
+          'arguments' => arguments,
+          'context' => []
+        }
+      else
+        temp['context'] << line
+      end
+    end
+    @__datalist__[temp['name']] = temp
+    return @__datalist__
+  end
+
+  # 按名称或属性选择数据项。
+  #
+  # @param options [Hash] 检索条件
+  #   - :name 按名称精确选择
+  #   - 其他键按数据项属性过滤（user/path/handler/...）
+  # @return [Hash, nil] 命中的数据项
+  def select options={}
+    if name = options[:name]
+      @__datalist__[name]
+    else
+      sets = @__datalist__.values
+      options.each do|key, val|
+        sets = sets.select{|s|s[key.to_s]==val.to_s}
+      end
+      sets.first
+    end
+  end
+
+  # 把数据项正文按解释器还原为 ruby / yaml / json / plaintext 对象。
+  #
+  # @param script [Hash, nil] parse 产生的数据项
+  # @return [Object, nil] 解析结果
+  def source script
+    return nil unless script && script['context']
+    context = script['context'].join("\n")
+    case script['handler']
+    when 'ruby'
+      context
+    when 'yaml'
+      YAML.load context
+    when 'json'
+      JSON.parse context
+    else # plaintext
+      context
+    end
+  end
+
+  # ruby inline：把数据段中的 ruby 文本在模块上下文中执行。
+  #
+  # @param scripts [String, nil] ruby 源码文本
+  # @yield [void] 无 scripts 时执行 block
+  # @return [Object] 执行结果
+  def run scripts=nil, &script_block
+    scripts ? self.module_eval(scripts) : self.module_eval(&script_block)
+  end
+end
+
+#------------------------------------------------------------------------------
+# EnData 应用层（移植自 imdoc/EnData/endata-app）
+#------------------------------------------------------------------------------
+module EnData
+  module_function
+
+  # 取回指定名称的表格数据（执行脚本内最常用的入口）。
+  #
+  # [CUSTOM_YOUR_NAME@endata CUSTOM_YOUR_PATH]$ruby table
+  #
+  # @param name [String] 表名，缺省 'table'；全局配置固定占用表名 'global'
+  # @return [Object] 表格数据（通常是二维数组）
+  def table name='table'
+    EnData.load()
+    EnData.parse()
+    EnData.run(EnData.source EnData.select name: name)
+  end
+
+  # 表1 × 表2 笛卡尔拼接（行对行叉积）。
+  #
+  # @param name1 [String] 左表名
+  # @param name2 [String] 右表名
+  # @return [Array<Array>] 拼接结果新表
+  def join_table name1, name2
+    table1 = EnData.table(name1)
+    table2 = EnData.table(name2)
+    table1.绑定表头 table1.first
+    table2.绑定表头 table2.first
+    return table1.拼接 table2
+  end
+
+  # 取表格的数据体（去表头）。
+  #
+  # @param name [String] 表名
+  # @return [Array<Array>] 数据行列表
+  def get_body name
+    EnData.table(name)[1..-1]
+  end
+
+  # 把 table[head, record...] 档案化为 {字段=>值} 对象数组。
+  #
+  # CASE: table[head=[field*], record=[value*]] >----> tree{field=>value, ...}
+  #
+  # @param table [Array<Array>] 二维表
+  # @return [Array<Hash>] 对象数组
+  def make_doc table
+    return table[1..-1].inject([]) do|doc, record|
+      rec = {}
+      record.each_with_index{|value, index|rec[table[0][index]] = value}
+      doc.push rec; doc
+    end
+  end
+
+  # 把表中 ${引用名} 占位替换为引用文本，生成新表。
+  #
+  # CASE: ${refname} >--(replace)--> reftext
+  #
+  # @param table [Array<Array>] 二维表
+  # @param refname [String] 引用名
+  # @param reftext [String] 引用文本
+  # @return [Array<Array>] 替换结果新表
+  def make_ref table, refname, reftext
+    return table.inject([]) do|newtab, record|
+      newrec = []
+      record.each{|field|newrec << (field=="${#{refname}}" ? reftext : field)}
+      newtab.push newrec; newtab
+    end
+  end
+
+end