class RakuAST::Doc::Block { }

RakuAST::Doc::Block 类包含有关 RakuDoc 块的信息。

RakuAST 功能的支持在语言版本 6.e+ 中可用，并在 Rakudo 编译器版本 2023.02 中添加。在较早的语言版本中，仅在指定时可用

use experimental :rakuast;

对象内省§

通常在解析包含 RakuDoc 标记的 Raku 编程语言代码时创建 RakuAST::Doc::Block 对象。因此，大多数开发人员只需要了解如何内省创建的对象。

method type§

say "type = $block.type()";

返回块的类型。

method level§

say "level = $block.level()";

返回与级别关联的字符串。如果级别为 0，则它将返回一个空字符串。否则，它将返回整数值的字符串化。

method config§

say "allows: $_"
  with $block.config<allow> andthen .literalize;

返回带有任何配置的 Map。请注意，您可以通过调用 .literalize 方法获取任何常量值。另请参见 resolved-config。

method resolved-config§

say "allows: $_" with $block.resolved-config<allow>;

返回带有任何配置的 Map，其中值已解析为“普通”Raku 对象。另请参见 config。

如果对象是由 Raku 语法创建的，则默认情况下可用。如果对象是“手动”创建的，则必须先调用 literalize-config 方法一次。

method paragraphs§

for $block.paragraphs {
    say $_;
}

返回段落的 List。请注意，每个元素可以是字符串、RakuAST::Doc::Paragraph 或另一个 RakuAST::Doc::Block 对象。

method delimited§

with $block {
    say "=begin $_.type" if .block;
}

返回一个 Bool，表示该块是一个定界块（又称带有 =begin 和 =end）。

method for§

with $block {
    say "=for $_.type" if .for;
}

返回一个Bool，表示该块是一个扩展块（又称仅包含一个=for。

方法 abbreviated§

with $block {
    say "=$_.type" if .abbreviated;
}

返回一个Bool，表示该块是一个缩写块（又称仅包含=后跟类型，例如=foo）。

方法 directive§

with $block {
    say "=$_.type" if .directive;
}

返回一个Bool，表示该块是一个RakuDoc指令（又称仅包含=后跟类型，例如=row）。

方法 allowed-markup§

my %*OK := $block.allowed-markup;
say "B markup is allowed" if %*OK<B>;

返回一个特殊用途的Map，可以检查该块中是否允许给定的标记类型，假设为RakuDoc语义。通常绑定到动态变量，因此可以访问所有内部RakuAST::Doc::Markup对象进行渲染。

可以返回三种类型的Map

• 来自:allow配置的真实Map

• Map的子类，对所有大写字母返回True

• Map的子类，始终返回False

方法 Str§

put $block;  # bar␤ 

返回块段落的字符串，其中任何标记也已字符串化。

方法 raku§

# method .gist falls back to .raku 
say $block;  # RakuAST::Doc::Block.new(... 

返回使用RakuAST调用创建块所需的字符串。

对象创建§

人们很少直接创建RakuAST::Doc::Block对象。本说明文档适用于那些希望设计自己的方式以编程方式构建RakuAST::Doc::Block对象的人员。

方法 new§

method new(
  Str:D  :$type!,        # type of block, e.g. "head" 
  Int:D  :$level = 0,    # level of block, e.g. 1 for "=head1" 
         :%config,       # any configuration to be applied 
  Str:D  :$margin = "",  # left margin (0 or more spaces) 
         :@paragraphs,   # paragraphs of this block 
  Bool:D :$for,          # this is a =for block 
  Bool:D :$abbreviated,  # this is an abbreviated block 
  Bool:D :$directive     # this is a directive (also abbreviated) 
)

可以调用new方法来创建一个新的RakuAST::Doc::Block对象。它只接受命名参数，其中:type参数是必需的。

  =begin foo
  bar
  =end foo
 
my $block = RakuAST::Doc::Block.new(
  :margin("  "),
  :type<foo>,
  :paragraphs("bar\n",)
);

请注意，段落不应包含左边界空白。

:type§

块的类型：这是一个带有名称的字符串。必需。允许使用任何名称，但RakuDoc标准为某些名称分配了语义。当使用这些名称时，假定块的行为将遵循RakuDoc标准语义。

:level§

块的级别，指定为整数值，默认为 0。RakuDoc中的一些块可以与名称关联一个数字，例如=item1和=head2。

:config§

与该块关联的任何配置，默认为无。指定为 Associative。请注意，指定时，值必须是 RakuAST:: 对象。因此，类似

frobnicate => 42

应指定为

frobnicate => RakuAST::IntLiteral.new(42)

:margin§

要应用的左边界，特别是在反解析时。应由 0 个或多个空格组成。默认为空字符串。

:paragraphs§

块的实际内容，指定为 Positional。每个元素可以是字符串、RakuAST::Doc::Paragraph 或另一个 RakuAST::Doc::Block 对象。如果是字符串，则假定已从字符串中的每行删除了 :margin。

:for, :abbreviated, :directive§

块格式的互斥指示，主要用于反解析。如果指定了 :for，则假定它是一个 =for 块。如果指定了 :abbreviated，则假定它是一个 =$type 块。如果指定了 :directive，则假定它是一个缩写块，该块只能作为缩写块出现并且具有特殊的 RakuDoc 语义（例如 =row 或 =column）。

如果未指定其中任何一个，则将假定一个“分隔块”（带有 =begin 和 =end 的块）。

方法 from-paragraphs§

根据要被视为段落的多个字符串创建一个 RakuAST::Doc::Block。假定字符串尚未删除左边界。

  =begin foo
  bar
  =end foo
 
my $block = RakuAST::Doc::Block.from-paragraphs(
  :margin("  "),
  :type<foo>,
  :paragraphs("  bar\n",)
);

采用与 new 相同的参数。请注意，段落应仅包含字符串，不应包含左边界空格。如果字符串的左边界小于用 :margin 指示的边界，将发出 worry/warning。

另请注意，将应用 RakuDoc 语义，例如

• 隐式代码块

• =table 的自动行/列检测

• 在（隐式）激活时的标记检测

对象修改§

方法 set-margin§

$block.set-margin("    ");

将边界设置为给定值，该值应为空字符串或 1 个或多个空格。

方法 set-type§

$block.set-type("foo");

将类型设置为给定值，该值应为字符串。

方法 set-level§

$block.set-level(1);

将级别设置为给定值，该值应为整数。

方法 set-config§

$block.set-config({
  numbered => RakuAST::Term::True.new;
});

将配置设置为给定值，该值应为 Associative，其中值是 RakuAST 对象。

方法 add-config§

$block.add-config(
  'allow',
  RakuAST::QuotedString.new(
    processors => <words val>,
    segments   => (
      RakuAST::StrLiteral.new("B C"),
    )
  )
);

获取一个键和一个值以添加到配置中。值应为字符串或 RakuAST 对象。

set-paragraphs 方法§

$block.set-paragraphs( ("foo\n\n","bar\n") );

将段落设置为给定的 Positional。值应为字符串或 RakuAST::Doc::Paragraph 对象。

add-paragraph 方法§

$block.add-paragraph("baz\n\n");

添加段落：应为字符串或 RakuAST::Doc::Paragraph 对象。

literalize-config 方法§

$block.literalize-config;
say "allowed are: $block.resolved-config<allowed>";

递归地将块的 config（如果有）文字化，并将结果放入 resolved-config 中。

如果对象是从 Raku 语法创建的，则无需调用此方法，因为它已作为 CHECK 阶段器检查的一部分被调用。

类型图§