class RakuAST::Doc::Declarator { }

The RakuAST::Doc::Declarator class contains the leading and trailing documentation of an object doing the RakuAST::Doc::DeclaratorTarget role.

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::Declarator objects are typically created when parsing Raku Programming Language code that has objects with leading (#|) and trailing (#=) documentation on it. So most developers will only need to know how to introspect the objects created.

method WHEREFORE

say "attached to a $declarator.WHEREFORE.^name() object";

Returns the object for which this object contains the declarator documentation.

method leading

.say for $declarator.leading;

Returns the lines of the leading declarator documentation (one for each line with #| if the object was created from parsing Raku source code.

method trailing

.say for $declarator.trailing;

Returns the lines of the trailing declarator documentation (one for each line with #= if the object was created from parsing Raku source code.

method raku

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

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

Object creation

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

method new

method new(
  Str:D :$WHEREFORE,  # the associated RakuAST object
        :@leading,    # leading lines of documentation
        :@trailing    # trailing lines of documentation
)

The new method can be called to create a new RakuAST::Doc::Declarator object. It only takes named arguments.

# there is no syntax for creating just a ::Declarator object

my $declarator = RakuAST::Doc::Declarator.new(
  :WHEREFORE(RakuAST::VarDeclaration::Simple.new(...)),
  :leading("line 1 leading","line 2 leading"),
  :trailing("line 1 trailing","line 2 trailing")
);

Note that the leading and trailing documentation may contain any left margin whitespace.

:WHEREFORE

The RakuAST object for which this declarator contains the documentation.

:leading

A Positional with the lines of leading documentation strings.

:trailing

A Positional with the lines of trailing documentation strings.

Object modification

method set-WHEREFORE

$declarator.set-WHEREFORE($object);

Set the object for which the RakuAST::Doc::Declarator object contains the documentation.

method set-leading

$declarator.set-leading;  # reset
$declarator.set-leading("foo", "bar");

Set the leading documentation. If no arguments are specified, reset to not having any leading documentation.

method add-leading

$declarator.add-leading("additional");

Add a line to the leading documentation.

method set-trailing

$declarator.set-trailing;  # reset
$declarator.set-trailing("foo", "bar");

Set the trailing documentation. If no arguments are specified, reset to not having any trailing documentation.

method add-trailing

$declarator.add-trailing("additional");

Add a line to the trailing documentation.