2015-12-20 2 views
5

я могу документировать такую ​​функцию:Документирование для Rebol

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)? Должен ли я делать это вручную?

ответ

4

В настоящее время ничего нет, но это хорошая идея. Так хорошо, что someone has suggested it раньше. :-)

Должен ли я сделать это вручную?

Вы можете вручную написать новый генератор, который определяет ваш формат диалекта. Затем либо сделайте что-нибудь вроде команды 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}] 

Методы, используемые здесь:

  • Soft Цитирование - Обычно вы должны сказать mumble 'help к «котировка «помощь как зажженное слово! чтобы передать это слово! (в отличие от запуска команды HELP по умолчанию). Но поскольку arg был объявлен в сгенерированной функции как 'arg, он был «мягким», это означает, что слова и пути не будут оцениваться. (Parens, get-words и get-paths все равно будут.) Это компромисс, потому что это означает, что если у кого-то есть переменная, которую они хотят передать вам, они должны сказать : var или (var) как аргумент вместо того, чтобы просто var (представьте, если блок для прохождения диалекта находится в переменной), поэтому вы не обязательно хотите его использовать ... но я подумал, что это интересная демонстрация, чтобы сделать mumble help работать без освещенного слова!

  • Deep Состав - The spec и body переменные, которые передаются в make-dialect существовать только до тех пор, как make-dialect работает. Как только все закончится, их не будет. Таким образом, вы не можете оставить эти слова в теле функции, которую вы создаете. Это использует COMPOSE/DEEP для оценки parens в теле до того, как генератор функций работает, чтобы сделать результат, эффективно извлекая данные для блоков и сшивая их в структуру тела функции.

  • Binding Работа реиспользования Function в - Сформированная функции имеет спецификацию с параметром arg, что не существовали на месте вызова из make-dialect. Так что арг должен отскок к чему-то, но что? Это можно сделать вручную, но один простой способ - позволить FUNC выполнять работу за вас.

Таковы некоторые из методов, которые будут использоваться в предлагаемом решении, которое стремится не только диалекты документа, но обеспечивают простой способ, с помощью которого их ключевые слова могут быть переносила (например, если чья система Rebol была сконфигурирована для другого разговорного языка).

Смежные вопросы