txt: ## markup.md
  class RakuAST::Doc::Markup
  
  Contains the information about RakuDoc markup
  
  ```raku
  class RakuAST::Doc::Markup { }
  ```
  
  The `RakuAST::Doc::Markup` class contains the information about markup codes in a [`RakuAST::Doc::Paragraph`](/type/RakuAST/Doc/Paragraph) or another `RakuAST::Doc::Markup` object.
  
  Support for [`RakuAST`](/type/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:
  
  ```raku
  use experimental :rakuast;
  ```
  
  ## [Object introspection](#class_RakuAST::Doc::Markup "go to top of document")[§](#Object_introspection "direct link")
  
  `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](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_letter "direct link")
  
  ```raku
  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](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_opener "direct link")
  
  ```raku
  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](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_closer "direct link")
  
  ```raku
  say "closer = $markup.closer()";  # >␤
  
  ```
  
  Returns the string that indicates the closer of the markup. This is typically ">", ">>" or "»". It is mostly intended to be used for stringification of the `RakuAST::Doc::Markup` object.
  
  ### [method atoms](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_atoms "direct link")
  
  ```raku
  .say for $markup.atoms;  # and␤
  
  ```
  
  Returns a [`List`](/type/List) of the atoms. Note that each element can either be a string or another `RakuAST::Doc::Markup` object.
  
  ### [method meta](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_meta "direct link")
  
  ```raku
  .say for $markup.meta;
  
  ```
  
  Returns a [`List`](/type/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](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_Str "direct link")
  
  ```raku
  put $markup;  # B<and>␤
  
  ```
  
  Returns the string for the markup object, with any embedded markup also stringified.
  
  ### [method raku](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_raku "direct link")
  
  ```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`](/type/RakuAST) calls.
  
  # [Object creation](#class_RakuAST::Doc::Markup "go to top of document")[§](#Object_creation "direct link")
  
  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](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_new "direct link")
  
  ```raku
  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.
  
  Rakudoc highlighting
  
  ```
  B<and>
  
  ```
  
  ```raku
  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](#class_RakuAST::Doc::Markup "go to top of document")[§](#:letter "direct link")
  
  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](#class_RakuAST::Doc::Markup "go to top of document")[§](#:opener "direct link")
  
  The markup opening sequence marker. Defaults to `"<"`. Mostly used for stringification.
  
  ### [:closer](#class_RakuAST::Doc::Markup "go to top of document")[§](#:closer "direct link")
  
  The markup closing sequence marker. Defaults to `">"`. Mostly used for stringification.
  
  ### [:atoms](#class_RakuAST::Doc::Markup "go to top of document")[§](#:atoms "direct link")
  
  The actual content of the markup, specified as a [`Positional`](/type/Positional). Each element can either be a string or another `RakuAST::Doc::Markup` object.
  
  ### [:meta](#class_RakuAST::Doc::Markup "go to top of document")[§](#:meta "direct link")
  
  The meta-information of the markup, specified as a [`Positional`](/type/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](#class_RakuAST::Doc::Markup "go to top of document")[§](#Object_modification "direct link")
  
  ## [method set-atoms](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_set-atoms "direct link")
  
  ```raku
  $markup.set-atoms;  # reset
  $markup.set-atoms( ("and",) );
  
  ```
  
  Set the atoms to the given [`Positional`](/type/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](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_add-atom "direct link")
  
  ```raku
  $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](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_set-meta "direct link")
  
  ```raku
  $markup.set-meta;  # reset
  $markup.set-meta( ("https://raku.org",) );
  
  ```
  
  Set the meta-information to the given [`Positional`](/type/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](#class_RakuAST::Doc::Markup "go to top of document")[§](#method_add-meta "direct link")
  
  ```raku
  $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.
  