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 .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 .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 .paragraphs
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
Returns a Bool
indicating the block is a delimited block (aka with a =begin
and an =end
.
method for§
with
Returns a Bool
indicating the block is an extended block (aka with just a =for
.
method abbreviated§
with
Returns a Bool
indicating the block is an abbreviated block (aka with just =
followed by the type, e.g. =foo
).
method directive§
with
Returns a Bool
indicating the block is a RakuDoc
directive (aka with just =
followed by the type, e.g. =row
).
method allowed-markup§
my := .allowed-markup;say "B markup is allowed" if <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 Map
s can be returned:
a real
Map
from the:allow
configurationa subclass of
Map
that returnsTrue
for all uppercase lettersa subclass of
Map
that always returnsFalse
method Str§
put ; # bar
Returns the string for the paragraphs of the block, with any markup also stringified.
method raku§
# method .gist falls back to .rakusay ; # 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 :!, # type of block, e.g. "head"Int : = 0, # level of block, e.g. 1 for "=head1":, # any configuration to be appliedStr : = "", # left margin (0 or more spaces):, # paragraphs of this blockBool :, # this is a =for blockBool :, # this is an abbreviated blockBool : # 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 foobar=end foomy = 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 foobar=end foomy = 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§
.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-type("foo");
Set the type to the given value, which is expected to be a string.
method set-level§
.set-level(1);
Set the level to the given value, which is expected to be an integer.
method set-config§
.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§
.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§
.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§
.add-paragraph("baz\n\n");
Add a paragraph: should be a string, or a RakuAST::Doc::Paragraph
object.
method literalize-config§
.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.