documentation - 记录 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 来识别它。
一个非常简短的例子来展示一组技术，这些技术可能在做这样的事情时派上用场(并非所有的都被认为是显而易见的，而是暗示灵 active ):

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 (想象一下，如果传递方言的 block 在一个变量中)所以你不一定想使用它......但我认为这是一个有趣的演示 mumble help工作没有点燃的话!

深层构图 - spec和 body传递给 make-dialect 的变量只存在于 make-dialect在跑。一旦结束，他们就会消失。所以你不能把这些词留在你正在生成的函数的主体中。这使用 COMPOSE/DEEP 在函数生成器运行生成结果之前评估主体中的括号，有效地提取 block 的数据并将它们缝合到函数的主体结构中。

重用函数的绑定(bind)工作 - 生成的函数有一个带有参数的规范 arg make-dialect 的调用站点上不存在的.所以 arg 必须被反弹到某个东西上，但是什么？可以手动完成，但一种简单的方法是让 FUNC 为您完成工作。

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