class RakuAST::Doc::Markup { }

The RakuAST::Doc::Markup class contains the information about markup codes in a RakuAST::Doc::Paragraph or another RakuAST::Doc::Markup object.

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::Markup 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 letter

say "letter = $markup.letter()";  # B␤

Returns the letter of the markup. This is usually an uppercase letter (any Unicode codepoint with the "Lu" property), such as B, but can also be a letter like Δ.

method opener

say "opener = $markup.opener()";  # <␤

Returns the string that indicates the opener of the markup. This is typically "<", "<<" or "«". It is mostly intended to be used for stringification of the RakuAST::Doc::Markup object.

method closer

say "closer = $markup.closer()";  # >␤

Returns the string that indicates the opener of the markup. This is typically ">", ">>" or "»". It is mostly intended to be used for stringification of the RakuAST::Doc::Markup object.

method atoms

.say for $markup.atoms;  # and␤

Returns a List of the atoms. Note that each element can either be a string or another RakuAST::Doc::Markup object.

method meta

.say for $markup.meta;

Returns a List of the metaobjects. Note that each element can either be a string or another RakuAST::Doc::Markup object. The RakuDoc standard assigns meaning to the meta-information of markup for certain letters, such as a URL (in case of L).

method Str

put $markup;  # B<and>␤

Returns the string for the markup object, with any embedded markup also stringified.

method raku

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

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

Object creation

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

method new

method new(
  Str:D  :$letter!,      # markup identifier, e.g. "B"
  Str:D  :$opener = "<", # opener marker
  Str:D  :$closer = ">", # closer marker
         :@atoms,        # any atoms of this markup
         :@meta,         # any meta of this markup
)

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

B<and>

my $markup = RakuAST::Doc::Markup.new(
  :letter<B>,
  :atoms("and")
);

Note that all arguments except :letter are optional. So it is possible to create "empty" markup as well.

:letter

The "type" of markup object. Generally expected to be an uppercase letter, but this is not enforced. The RakuDoc standard assigns meaning to most ASCII uppercase letters, so one would probably do well adhering to this standard when using ASCII uppercase letters.

:opener

The markup opening sequence marker. Defaults to C<<"<">>. Mostly used for stringification.

:closer

The markup closing sequence marker. Defaults to <">">. Mostly used for stringification.

:atoms

The actual content of the markup, specified as a Positional. Each element can either be a string or another RakuAST::Doc::Markup object.

:meta

The meta-information of the markup, specified as a Positional. Each element can either be a string or another RakuAST::Doc::Markup object. Note that the RakuDoc standard associates certain meaning to the meta-information for certain letters, such as the meta-information being a URL in the case of L being the letter.

Object modification

method set-atoms

$markup.set-atoms;  # reset
$markup.set-atoms( ("and",) );

Set the atoms to the given Positional. Values are expected to be either a string, or a RakuAST::Doc::Markup object. If no values are specified, then the object will have no atoms.

method add-atom

$markup.add-atom( ("foo",) );

Add an atom to the atoms of the object. Values are expected to be either a string, or a RakuAST::Doc::Markup object.

method set-meta

$markup.set-meta;  # reset
$markup.set-meta( ("https://raku.org",) );

Set the meta-information to the given Positional. Values are expected to be either a string, or a RakuAST::Doc::Markup object. If no values are specified, then the object will have no meta-information.

method add-meta

$markup.add-meta( ("bar",) );

Add an item to the meta-information of the object. Values are expected to be either a string, or a RakuAST::Doc::Markup object.