记录 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

目前没有任何东西，但这是个好主意。好到someone has suggested it之前。 :-)

Do I have to do this manually?

您可以手动编写一个新的生成器来定义您的“方言规范”格式。然后要么做一些像给它一个 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 的情况下工作是一个有趣的演示！
Deep Composition - 传递给 make-dialect 的 spec 和 body 变量仅存在因为 make-dialect 是运行。一旦结束，他们就会消失。所以你不能把这些词留在你正在生成的函数的主体中。这使用 COMPOSE/DEEP 在函数生成器运行以生成结果之前评估主体中的括号，有效地提取块的数据并将它们拼接到函数的主体结构中。
重用函数的绑定工作 - 生成的函数有一个参数 arg 的规范，在 make-dialect。所以 arg 必须反弹到某些东西，但是什么？可以手动完成，但一种简单的方法是让 FUNC 为您完成工作。

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

记录 Rebol 的方言

Documenting Rebol's dialect

documentation

rebol