Rules / Types, classes & roles / basic

RakuAST::Doc::Block Reference

Contains the information of a RakuDoc block

What it is #

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method `new` #

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. Note that the paragraphs should not contain the left margin whitespace. 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

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. 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.

method `set-margin` #

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

method `set-type` #

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

method `set-level` #

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

method `set-config` #

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

method `add-config` #

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` #

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

method `add-paragraph` #

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

method `literalize-config` #

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.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

27 no-output

class RakuAST::Doc::Block { }

Not executed: the documentation states no expected output for this example.

use experimental :rakuast;

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

for $block.paragraphs {
say $_;
}

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

put $block;  # bar␤

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

  =begin foo
  bar
  =end foo

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

Not executed: the documentation states no expected output for this example.

frobnicate => 42

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

  =begin foo
  bar
  =end foo

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

Not executed: the documentation states no expected output for this example.

$block.set-margin("    ");

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

$block.set-level(1);

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.

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

Not executed: the documentation states no expected output for this example.