txt: ## dist_zef-jjmerelo-Pod-Utils.md
  # NAME [Test-install distro](https://github.com/JJ/raku-pod-utils/actions/workflows/test.yaml)
  
  Pod::Utils - Set of helper functions to ease working with Pods!
  
  # SYNOPSIS
  
  ```
      use Pod::Utils;
  
      # time to work with Pod::* elements!
      say first-subtitle($=pod[0].contents);
  
      =begin pod
  
      =SUBTITLE Some cool text
  
      =end pod
  
  ```
  
  # DESCRIPTION
  
  Pod::Utils is a set of routines that help you to deal with Pod elements.
  It lets you manipulate several kinds of Pod objects, obtain gists and modify
  headings.
  
  ### sub first-code-block
  
  ```
  sub first-code-block (
      Array @pod
  ) returns Str;
  
  ```
  
  Returns the first `Pod::Block::Code` found in an array, concatenating all lines in it.
  If none is found, it will return an empty string.
  
  Example:
  
  ```
  =begin pod
  =begin code
  
      say "some code";
      say "more code";
  
  =end code
  =end pod
  
  first-code-block($=pod[0].contents)
  
  # OUTPUT «say "some code";␤say "more code";␤»
  
  ```
  
  ### sub first-title
  
  ```
  sub first-title (
      Array @pod
  ) returns Pod::Block::Named;
  
  ```
  
  Returns the first `=TITLE` element found in `@pods`.
  
  Example:
  
  ```
  =begin pod
  
  =TITLE title
  
  =end pod
  
  first-title($=pod[0].contents)
  
  # OUTPUT equivalent to:
  
  =TITLE title
  
  
  ```
  
  ### sub first-subtitle
  
  ```
  sub first-subtitle (
      Array @pod
  ) returns Pod::Block::Named;
  
  ```
  
  Returns the first `=SUBTITLE` element found in `@pods`.
  
  Example:
  
  ```
  =begin pod
  
  =subTITLE subtitle
  
  =end pod
  
  first-subtitle($=pod[0].contents)
  
  # OUTPUT equivalent to:
  
  =SUBTITLE subtitle
  
  
  ```
  
  ### multi sub textify-guts
  
  ```
  multi textify-guts (Any:U,       ) return Str;
  multi textify-guts (Str:D      \v) return Str;
  multi textify-guts (List:D     \v) return Str;
  multi textify-guts (Pod::Block \v) return Str;
  
  ```
  
  Converts lists of `Pod::Block::*` objects and `Pod::Block` objects to strings.
  
  Example:
  
  ```
  my $block = Pod::Block::Para.new(contents => ["block"]);
  say textify-guts($block); # OUTPUT «block␤»
  say textify-guts([$block, $block]); # OUTPUT «block block␤»
  
  ```
  
  ### multi sub recurse-until-str
  
  ```
  multi sub recurse-until-str(Str:D $s)      return Str;
  multi sub recurse-until-str(Pod::Block $n) return Str;
  
  
  ```
  
  Accepts a `Pod::Block::*` object and returns a concatenation of all subpods content.
  
  Example:
  
  ```
  my $block         = Pod::Block::Para.new(contents => ["block"]);
  my $complex-block = pod-block("one", pod-block("two"), pod-bold("three"));
  say recurse-until-str($block); # OUTPUT «block␤»
  say recurse-until-str($complex-block); # OUTPUT «onetwothree␤»
  
  ```
  
  # Pod::Utils::Build
  
  # SYNOPSIS
  
  ```
      use Pod::Utils::Build;
  
      # time to build Pod::* elements!
      say pod-bold("bold text");
  
  ```
  
  # DESCRIPTION
  
  Pod::Utils::Build is a set of routines that help you to create new
  Pod elements.
  
  ### sub pod-title
  
  ```
  sub pod-title (
      Str $title,
  ) returns Pod::Block::Named;
  
  ```
  
  Creates a new `Pod::Block::Named` object (with `:name` set to `"TITLE"`)
  and populates it with a `Pod::Block::Para` containing `$title`.
  
  Example:
  
  ```
  
  pod-title("title");
  
  # OUTPUT Equivalent to:
  
  =begind pod
  
  =TITLE title
  
  =end pod
  
  ```
  
  ### sub pod-with-title
  
  ```
  sub pod-with-title (
      Str $title,
      Array @blocks
  ) returns Pod::Block::Named;
  
  ```
  
  Creates a new `Pod::Block::Named` object (with `:name` set to "pod")
  and populate it with a title (using `pod-title`) and `@blocks`.
  
  Example:
  
  ```
  
  =begind pod
  
  Normal paragraph
  
  =end pod
  
  pod-with-title("title", $=pod.first.contents[0]);
  
  # OUTPUT Equivalent to:
  
  =beging pod
  
  =TITLE title
  
  Normal paragraph
  
  =end pod
  
  ```
  
  ### sub pod-block
  
  ```
  sub pod-block (
      Array *@contents
  ) returns Pod::Block::Para;
  
  ```
  
  Creates a `Pod::Block::Para` with contents set to `@contents`.
  
  Example:
  
  ```
  
  
  say pod-block("title", Pod::Block::Para.new(contents => ["paragraph"]));
  
  # OUTPUT
  
  Pod::Block::Para
    title
    Pod::Block::Para
      paragraph
  
  
  ```
  
  ### sub pod-link
  
  ```
  sub pod-link (
      Str $text,
      Str $url
  ) returns Pod::FormattingCode;
  
  ```
  
  Creates a `Pod::FormattingCode` (type Link) with contents set to `$text`.
  and meta set to `$url`.
  
  Example:
  
  ```
  
  pod-link("text","url");
  
  # OUTPUT Equivalent to:
  
  L<text|url>
  
  ```
  
  ### sub pod-bold
  
  ```
  sub pod-bold (
      Str $text,
  ) returns Pod::FormattingCode;
  
  ```
  
  Creates a `Pod::FormattingCode` (type B) with contents set to `$text`.
  
  Example:
  
  ```
  
  pod-bold("text");
  
  # OUTPUT Equivalent to:
  
  B<text>
  
  ```
  
  ### sub pod-code
  
  ```
  sub pod-code (
      Str $text,
  ) returns Pod::FormattingCode;
  
  ```
  
  Creates a `Pod::FormattingCode` (type C) with contents set to `$text`.
  
  Example:
  
  ```
  
  pod-code("text");
  
  # OUTPUT Equivalent to:
  
  C<text>
  
  ```
  
  ### sub pod-item
  
  ```
  sub pod-item (
      Array *@contents ,
      Int   :$level = 1,
  ) returns Pod::Item;
  
  ```
  
  Creates a `Pod::Item` object with contents set to `@contents` and level to `$level`.
  
  Example:
  
  ```
  
  pod-item(pod-block("item"), level => 1);
  
  # OUTPUT Equivalent to:
  
  =item item
  
  
  ```
  
  ### sub pod-heading
  
  ```
  sub pod-heading (
      Str   $name,
      Int   :$level = 1,
  ) returns Pod::Heading;
  
  ```
  
  Creates a `Pod::Heading` object with level set `$level` and contents initialized
  with a `Pod::Block::Para` object containing `$name`.
  
  Example:
  
  ```
  
  pod-heading("heading", level => 1);
  
  # OUTPUT Equivalent to:
  
  =head1 heading
  
  
  ```
  
  ### sub pod-table
  
  ```
  sub pod-table (
      Array @contents,
      Array :@headers,
  ) returns Pod::Block::Table;
  
  ```
  
  Creates a `Pod::Block::Table` object with the headers `@headers` and rows `@contents`.
  `$caption` is set to `""`.
  Example:
  
  ```
  
  pod-table([["col1", "col2"],], headers => ["h1", "h2"]);
  
  # OUTPUT Equivalent to:
  
  =begin table
  
  h1   | h2
  ============
  col1 | col2
  
  =end table
  
  
  ```
  
  ### sub pod-lower-headings
  
  ```
  sub pod-lower-headings (
      Array @content,
      Int   :$to,
  ) returns Array;
  
  ```
  
  Given an array of Pod objects, lower the level of every heading following
  the next formula => `current-level - $by + $to`, where `$by` is the level of the
  first heading found in the array.
  
  Example:
  
  ```
  
  my @contents = [
      pod-heading("head", level => 2),
      pod-heading("head", level => 3)
  ];
  
  pod-lower-headings(@contents)
  
  # OUTPUT Equivalent to:
  
  =head1 head
  
  =head2 head
  
  
  ```
  
  # AUTHORS
  
  Alexander Mouquin <@Mouq>
  
  Will Coleda <@coke>
  
  Rob Hoelz <@hoelzro>
  
  <@timo>
  
  Moritz Lenz <@moritz>
  
  Juan Julián <@JJ>
  
  <@MasterDuke17>
  
  Zoffix Znet <@zoffixznet>
  
  Antonio <@antoniogamiz>
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2019 Perl 6 team
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  