Marvin's Blog【程式人生】

Ability will never catch up with the demand for it

23 May 2021

Racket的文档工具Scribble阅读笔记【一】

Scribble: The Racket Documentation Tool阅读笔记

2 @ Syntax

scribble使用@在文本中插入s-表达式。选用@是因为它在正常的代码中很少出现。

在scribble/base或者其他类似语言中,@自动可得。使用at-exp元语言也可以添加对@的支持:

#lang at-exp racket
  (define v '@op{str})

等同于:

#lang racket
(define v '(op "str"))

2.1 The Scribble Syntax at a Glance

@构造的格式:

@ ‹cmd› [ ‹datum›* ] { ‹text-body›* }

@后面的三个部分都是可选的,但至少要出现一个。部分之间不能出现空格。

#lang at-exp racket
'@foo{blah blah blah}

会被翻译成

(foo "blah blah blah")

更多例子:

  • @foo{blah "blah" (blah’?)}读成(foo “blah "blah" (blah'?)")
  • @foo[1 2]{3 4} 读成 (foo 1 2 "3 4")
  • @foo[1 2 3 4] 读成 (foo 1 2 3 4)
  • @foo[#:width 2]{blah blah} 读成 (foo #:width 2 "blah blah")
@foo{blah blah
     yada yada}

会被翻译成

(foo "blah blah" "\n"
     "yada yada")
@foo{
  blah blah
  yada yada
}

会被翻译成

(foo
  "blah blah" "\n"
  "yada yada")

可以看到,‹text-body›中的缩进不一定会被保留,但是换行则会被保留。

更方便的是,可以在‹text-body›中嵌套@构造:

@foo{bar @baz{3}
     blah}

会被翻译为

(foo "bar " (baz "3") "\n"
     "blah")

如果不使用datum和text部分,那么:

  • @foo 读成 foo
  • @{blah @foo: blah} 读成 ("blah " foo: " blah")
  • @{blah @|foo|: blah} 读成 ("blah " foo ": blah")

命令部分可以是任意表达式,只要不以{[,或者|开头:

  • @foo{(+ 1 2) -> @(+ 1 2)!} 读成 (foo "(+ 1 2) -> " (+ 1 2) "!")
  • @foo{A @"string" escape} 读成 (foo "A string escape")
  • @"@" 读成 “@”

转义的”@“会与环绕的字符串融合:

  • @foo{eli@"@"barzilay.org} 读成 (foo "eli@barzilay.org")

{这种,除非在text-body中成对出现,否则也需要转义。

可以使用|{}|来禁止默认的@构造:

  • @foo|{bar |@x|{@}| baz}| 读成 (foo "bar " (x "@") " baz")

如果上面的方法还不够,则可以使用下面的:

  • @foo|--{bar}@|{baz}--| 读成 (foo "bar}@|{baz")
  • @foo|<<{bar}@|{baz}>>| 读成 (foo "bar}@|{baz")

可否将@用作标识符名字的一部分?可以,不出现在首字母即可,若出现在首字母,则要用转义的办法:

  • (define \@email "foo@bar.com") 读成 (define @email "foo@bar.com")
  • (define |@atchar| #\@) 读成 (define @atchar #\@)

值得注意的是,@构造只是书写s-表达式的另一种形式而已,运算s-表达式时所需要的环境在运算@构造的时候也需要。

2.2 The Command Part

2.3 The Datum Part

2.4 The Body Part

2.4.1 Alternative Body Syntax

2.4.2 Racket Expression Escapes

2.4.3 Comments

可以使用@;{...}以及@;...来添加注释。前者可以嵌套,并且里面的换行算数;后者不可以嵌套,但会吃掉行尾的换行。

2.4.4 Spaces, Newlines, and Indentation

@-构造对换行和空白有特定的处理方式。例如

{之后或者}之前的纯换行会被丢弃,除非{}之间的内容只有换行。

正文竖标线之前的空白会被忽略,竖标线的位置由具有最小缩进的非空行决定。

如果首行紧随{之后,那么它不会被缩进,但是它的位置会被竖标线参考。

每个@-构造都按自己的缩进来解析。嵌套的@-构造可以有自己的缩进。

如果输入端口的的行列计数没有打开,那么计算竖标线的时候不会参考正文中的首行。

极端情况下,如果行首空白很重要,可以使用@||插入空白:

@foo{
  @|| bar @||
  @|| baz}

上面的代码翻译成:

(foo
  " bar " "\n"
  " baz"

(未完待续)

Categories