class RakuAST::Doc::Block { }

The RakuAST::Doc::Block class contains the information about a RakuDoc block.

Support for RakuAST functionality is available in language version 6.e+ and was added in Rakudo compiler release 2023.02. In earlier language versions it is only available when specifying:

use experimental :rakuast;

Object introspection

RakuAST::Doc::Block objects are typically created when parsing Raku Programming Language code that has RakuDoc markers in it. So most developers will only need to know how to introspect the objects created.

method type

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

Returns the type of the block.

method level

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

Returns a string associated with the level. If the level is 0, then it will return an empty string. Otherwise it will return the stringification of the integer value.

method config

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

Returns the Map with any configuration. Note that you can get any constant values by calling the .literalize method on them. See also resolved-config.

method resolved-config

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

Returns the Map with any configuration, with the values already resolved to "normal" Raku objects. See also config.

Is available by default if the object was created by the Raku grammar. If the object was created "manually", then the literalize-config method must be called once first.

method paragraphs

for $block.paragraphs {
    say $_;
}

Returns a List of the paragraphs. Note that each element can either be a string, a RakuAST::Doc::Paragraph or another RakuAST::Doc::Block object.

method delimited

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

Returns a Bool indicating the block is a delimited block (aka with a =begin and an =end.

method for

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

Returns a Bool indicating the block is an extended block (aka with just a =for.

method abbreviated

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

Returns a Bool indicating the block is an abbreviated block (aka with just = followed by the type, e.g. =foo).

method directive

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

Returns a Bool indicating the block is a RakuDoc directive (aka with just = followed by the type, e.g. =row).

method allowed-markup

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

Returns a special purpose Map that can be checked to see whether a given markup type is allowed in the block, assuming RakuDoc semantics. Usually bound to a dynamic variable, so it can be accessible for rendering all inner RakuAST::Doc::Markup objects.

Three types of Maps can be returned:

• a real Map from the :allow configuration

• a subclass of Map that returns True for all uppercase letters

• a subclass of Map that always returns False

method Str

put $block;  # bar␤

Returns the string for the paragraphs of the block, with any markup also stringified.

method raku

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

Returns the string that is needed for the creation of the block using RakuAST calls.

Object creation

One seldom creates RakuAST::Doc::Block objects directly. This documentation is intended for those few people who'd like to devise their own way of programmatically building a RakuAST::Doc::Block object.

method 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)
)

The new method can be called to create a new RakuAST::Doc::Block object. It only takes named arguments, with the :type argument being mandatory.

  =begin foo
  bar
  =end foo

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

Note that the paragraphs should not contain the left margin whitespace.

:type

The type of block: this is a string with the name. Required. Any name is allowed, but the RakuDoc standard assigns semantics to some names. When these are used, it is assumed that the behavior of the block will adhere to the RakuDoc standard semantics.

:level

The level of the block, specified as an integer value, defaults to 0. Some blocks in RakuDoc can have a number associated with the name, such as =item1 and =head2.

:config

Any config to be associated with this block, defaults to none. Specified as an Associative. Note that when specified, the values must be RakuAST:: objects. So something like:

frobnicate => 42

should be specified as:

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

:margin

The left margin to be applied, specifically when deparsing. Should consist of 0 or more spaces. Defaults to the empty string.

:paragraphs

The actual content of the block, specified as a Positional. Each element can either be a string, a RakuAST::Doc::Paragraph or another RakuAST::Doc::Block object. In the case of a string, it is assumed that the :margin has already been removed from each line in the string.

:for, :abbreviated, :directive

Mutually exclusive indication of the format of the block, mostly used in deparsing. If :for is specified, it is assumed to be a =for block. If :abbreviated is specified, then it is assumed to be a =$type block. If :directive is specified, then is assume to be an abbreviated block that can only occur as an abbreviated block and has special RakuDoc semantics (e.g. =row or =column).

If neither of these are specified, then a "delimited block" (one with a =begin and an =end will be assumed.

method from-paragraphs

Create a RakuAST::Doc::Block from a number of strings to be considered paragraphs. Strings are assumed to not have removed the left margin yet.

  =begin foo
  bar
  =end foo

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

Takes the same arguments as new. Note that the paragraphs should only contain strings and should not contain the left margin whitespace. A worry/warning will be issued if the left margin of a string is less than the margin indicated with :margin.

Also note that RakuDoc semantics will be applied, such as:

• implicit code blocks

• automatic row/column detection for =table

• markup detection where (implicitly) activated

Object modification

method set-margin

$block.set-margin("    ");

Set the margin to the given value, which is expected to be the empty string or 1 more spaces.

method set-type

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

Set the type to the given value, which is expected to be a string.

method set-level

$block.set-level(1);

Set the level to the given value, which is expected to be an integer.

method set-config

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

Set the configuration to the given value, which is expected to be an Associative of which the values are RakuAST objects.

method add-config

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

Takes a key and a value to add to the configuration. Value is expected to be either a string or a RakuAST object.

method set-paragraphs

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

Set the paragraphs to the given Positional. Values are expected to be either a string, or a RakuAST::Doc::Paragraph object.

method add-paragraph

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

Add a paragraph: should be a string, or a RakuAST::Doc::Paragraph object.

method literalize-config

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

Recursively literalizes the config of the block (if any) and puts the result in resolved-config.

If the object was created from the Raku grammar, then there is no need to call this method ever, as it will have been called as part of the CHECK phaser checks already.