记录Rebol的方言

Question

我可以记录这样的函数:

f: func [
    "a description"
    arg1 [string!] "a description of an argument 1"
    ][
    arg1
    ]

我可以使用?/ help来检索有关函数的信息(描述,用法,参数列表,每个参数的描述及其类型)

? f
USAGE:
    F arg1

DESCRIPTION:
     a description
     F is a function value.

ARGUMENTS:
     arg1 -- a description of an argument 1 (Type: string)

我无法记录这样的方言.是否有自动记录方言的方式(func如果有)？我必须手动执行此操作吗？

Answer 1

目前还没有什么办法，但这是一个好主意。太好了，之前有人推荐过。:-)

我必须手动执行此操作吗？

您可以手动编写一个新的生成器来定义您的“方言规范”格式。然后要么执行一些操作，例如给它一个 HELP 命令，或者扩展 HELP 来识别它。

非常简短的示例，演示了一组可能在执行此类操作时派上用场的技术（并非所有技术都期望显而易见，而是暗示灵活性）：

make-dialect: function [spec [block!] body [block!]] [
    return function ['arg [block! word!]] compose/deep/only [
        case [
            arg = 'HELP [
                foreach keyword (spec/keywords) [
                    print [keyword "-" {your help here}]
                ]
            ]

            block? arg [
                do func [arg] (body) arg
            ]

            'default [
                print "Unrecognized command.  Try HELP."
            ]
        ]
    ]
]

因此，您的函数采用方言规范并创建一个函数。一旦你有了你的生成器，使用它就可以减少手动操作：

mumble: make-dialect [keywords: [foo baz bar]] [
    print ["arg is" mold arg]
]

>> mumble help
foo - your help here
baz - your help here
bar - your help here

>> mumble [<some> [dialect] {stuff}]
arg is [<some> [dialect] {stuff}]

这里使用的技术是：

• 软引用- 通常您必须将mumble 'help帮助作为一个简短的词“引用”！让它传递信息！咕哝（而不是运行默认的 HELP 命令）。但是因为 arg 在生成的函数中被声明为'arg“软引用”......这意味着单词和路径将不会被评估。（Parens、get-words 和 get-paths 仍然会是。）这是一个权衡，因为这意味着如果有人想要传递一个变量给你，他们必须说:var或(var)作为参数，而不是仅仅var(想象一下，如果传递方言的块位于变量中），那么您不一定想使用它......但我认为这是一个有趣的演示，可以在mumble help没有 lit-word 的情况下工作！

• 深层组合-传递的变量spec和变量仅在运行时存在。一旦结束，他们就会消失。因此，您不能将这些单词留在您正在生成的函数体内。在函数生成器运行以生成结果之前，它使用 COMPOSE/DEEP 来评估函数体中的括号，从而有效地提取块的数据并将它们拼接到函数体结构中。bodymake-dialectmake-dialect

• 重用函数的绑定工作- 生成的函数具有一个规范，其中的参数arg在 的调用站点上不存在make-dialect。所以 arg 必须反弹到某个东西，但是什么呢？可以手动完成此操作，但一种简单的方法是让 FUNC 为您完成这项工作。

这些是将在所提出的解决方案中使用的一些技术，该解决方案不仅旨在记录方言，而且提供一种可以重新映射其关键字的简单方法（例如，如果一个人的 Rebol 系统已配置为另一种口语）。