NAME

Pod::Contents - a Raku module for getting Pod contents as a list or string.

DESCRIPTION

Pod::Contents is a Raku module for getting the Pod contents as a list of strings or string.

Pod formatters can get inlined, pod contents can be indented (with custom level) and joined with a custom string and titles can be included for table headers and defn terms.

SYNOPSIS

use Pod::Contents:auth<zef:CIAvash>;
=NAME My App
=DESCRIPTION An B<app> that does U<stuff>=beginpod=head1 A heading
=item An B<item>=beginitem2Another C<item>=begintablehcell00 | hcell01
=================
cell11 | cell12
cell21 | cell22
=end table my $app;
 say 'some code';
=end item2=end pod
put $=pod.&join_pod_contents_of: 'NAME';
=output My App␤
put $=pod.&get_first_pod('NAME').&join_pod_contents;
=output My App␤
put $=pod[0].&join_pod_contents;
=output My App␤
put $=pod[0].&get_pod_contents.join("\n\n");
=output My App␤
put $=pod.&join_pod_contents_of: 'DESCRIPTION';
=output An app that does stuff␤
put $=pod.&join_pod_contents_of: 'DESCRIPTION', :!inline_formatters;
=output An ␤␤app␤␤ that does ␤␤stuff␤
put $=pod.&join_pod_contents_of: 'DESCRIPTION', "\n", :!inline_formatters;
=output An ␤app␤ that does ␤stuff␤
put $=pod.&get_pod_contents_of('DESCRIPTION', :!inline_formatters).raku;
=output ("An ", "app", " that does ", "stuff")␤
put $=pod.&get_first_pod('pod').&join_pod_contents_of: Pod::Heading;
=output A heading␤
put $=pod.&join_pod_contents_of: Pod::Item, :recurse;
=output An item␤
put $=pod.&get_pod_contents_of(Pod::Block::Table, :recurse).raku;
=output (("cell11", "cell12"), ("cell21", "cell22"))␤
put $=pod.&get_pod_contents_of(Pod::Block::Table, :recurse, :include_title).raku;
=output (("hcell00", "hcell01"), ("cell11", "cell12"), ("cell21", "cell22"))␤
put $=pod.&join_pod_contents_of: Pod::Block::Table, :recurse;
=output cell11 cell12␤cell21 cell22␤
put $=pod.&join_pod_contents_of: Pod::Block::Table, :recurse, :include_title;
=output hcell00 hcell01␤cell11 cell12␤cell21 cell22␤
put $=pod.&join_pod_contents_of: Pod::Block::Code, :recurse;
=output my $app;␤say 'some code'␤
put $=pod.&join_pod_contents_of: Pod::Block::Code, :indent_content, :recurse;
=output my $app;␤ say 'some code'␤
put $=pod.&get_first_pod('pod').contents.grep(Pod::Item)[1].&join_pod_contents(:indent_content);
=output Another item␤␤ cell11 cell12␤cell21 cell22␤␤ my $app;␤ say 'some code'␤
put $=pod.&get_first_pod('pod').&get_pods(Pod::Item)[1].&join_pod_contents(:indent_content, :indent_level(2));
=output Another item␤␤ cell11 cell12␤cell21 cell22␤␤ my $app;␤ say 'some code'␤
put $=pod.&get_pods(Pod::Item, :recurse)[1].&join_pod_contents(:indent_content, :indent_level(2));
=output Another item␤␤ cell11 cell12␤cell21 cell22␤␤ my $app;␤ say 'some code'␤

INSTALLATION

You need to have Raku and zef, then run:

zef install --/test Pod::Contents:auth<zef:CIAvash>

or if you have cloned the repo:

zef install .

TESTING

prove -ve 'raku -I.' --ext rakutest

SUBS

sub get_pod_contents_of

sub get_pod_contents_of(
 $pod where { ... },
 $thing where { ... },
 Bool :$recurse,
 |c
) returns List:D

Returns a list of pod contents.

• Can recursively find pod with :recurse.
• Can indent pod contents with :indent_content.
• Can include pod titles with :include_title.
• Can disable inlining pod formatters with :!inline_formatters.
• Can put same level items next to each other with :adjacent_items.

sub join_pod_contents_of

sub join_pod_contents_of(
 $pod where { ... },
 $thing where { ... },
 Bool :$recurse,
 |c
) returns Str:D

Joins pod contents of the requested Pod with the passed string or 2 newlines.

• Can recursively find pod with :recurse.
• Can indent pod contents with :indent_content.
• Can include pod titles with :include_title.
• Can disable inlining pod formatters with :!inline_formatters.
• Can put same level items next to each other with :adjacent_items.

sub get_first_pod

sub get_first_pod(
 $pod where { ... },
 $thing where { ... },
 Bool :$recurse
) returns Pod::Contents::POD

Finds the first Pod using the passed pod or name, does so recursively if :recurse is passed.

sub get_pods

sub get_pods(
 $pod where { ... },
 $thing where { ... },
 Bool :$recurse
) returns List:D

Finds all Pods using the passed pod or name, does so recursively if :recurse is passed

sub get_pod_contents

sub get_pod_contents(
 |
) returns Mu

Recursively gets the Pod contents of a Pod block as a list of (list of) strings.

• Can indent pod contents with :indent_content.
• Can include pod titles with :include_title.
• Can disable inlining pod formatters with :!inline_formatters.
• Can put same level items next to each other with :adjacent_items.

sub check_pod

sub check_pod(
 $pod where { ... },
 $pod_type where { ... }
) returns Bool is export(:helpers)

Returns True if pod matches pod_type

sub indent_content

sub indent_content(
 Str:D $string,
 Int:D $indent_level where { ... } = 4
) returns Str is export(:helpers)

Indents string by indent_level

REPOSITORY

https://codeberg.org/CIAvash/Pod-Contents/

BUG

https://codeberg.org/CIAvash/Pod-Contents/issues

AUTHOR

Siavash Askari Nasr - https://siavash.askari-nasr.com

COPYRIGHT

Copyright © 2021 Siavash Askari Nasr

LICENSE

This file is part of Pod::Contents.

Pod::Contents is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Pod::Contents is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with Pod::Contents. If not, see http://www.gnu.org/licenses/.