Skip to content
Helper functions to deal with Pod elements.
Other
  1. Other 100.0%
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib/Pod
t
.gitignore
.travis.yml
Changes
LICENSE
META6.json
README.md
dist.ini

README.md

Build Status

NAME

Pod::Utilities - Set of helper functions to ease working with Pods!

SYNOPSIS

    use Pod::Utilities;

    # time to work with Pod::* elements!
    say first-subtitle($=pod[0].contents);

    =begin pod

    =SUBTITLE Some cool text

    =end pod

DESCRIPTION

Pod::Utilities 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::Utilities::Build

SYNOPSIS

    use Pod::Utilities::Build;

    # time to build Pod::* elements!
    say pod-bold("bold text");

DESCRIPTION

Pod::Utilities::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.

You can’t perform that action at this time.