head

code

item

root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

README

Pod::Contents is a L<Raku|https://www.raku-lang.ir/en> 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.


Pod::Contents - a L<Raku|https://www.raku-lang.ir/en> module for getting Pod contents as a list or string.


NAME

DESCRIPTION

=begin code :lang<raku>

use Pod::Contents:auth<zef:CIAvash>;

=NAME My App

=DESCRIPTION An B<app> that does U<stuff>

=begin pod
=head1 A heading

=item An B<item>
=begin item2
Another C<item>

=begin table
hcell00 | 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'␤

=end code


SYNOPSIS

You need to have L<Raku|https://www.raku-lang.ir/en> and L<zef|https://github.com/ugexe/zef>,
then run:


=begin code :lang<console>

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

=end code


=begin code :lang<console>

zef install .

=end code


INSTALLATION

=begin code :lang<console>

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

=end code


TESTING


unit module Pod::Contents:auth($?DISTRIBUTION.meta<auth>):ver($?DISTRIBUTION.meta<version>);

subset SomePod       where Pod::Block | Pod::Heading     | Pod::FormattingCode;
subset IndentablePod where Pod::Item  | Pod::Block::Code | Pod::Defn;
subset POD           where SomePod    | IndentablePod;
subset StrOrPod      where Str:D      | POD;
subset ArrayOfPod of List where .all ~~ POD;
subset PodOrArrayOfPod where POD | ArrayOfPod;



SUBS


#| Returns a list of pod contents.
#| Can recursively find pod with C<:recurse>.
#| Can indent pod contents with C<:indent_content>.
#| Can include pod titles with C<:include_title>.
#| Can disable inlining pod formatters with C<:!inline_formatters>.
#| Can put same level items next to each other with C<:adjacent_items>.
sub get_pod_contents_of (PodOrArrayOfPod $pod, StrOrPod $thing, Bool :$recurse, |c --> List:D) is export {
    get_pod_contents $_, |c given get_first_pod $pod, $thing, :$recurse;
}

#| Joins pod contents of the requested Pod with the passed string or 2 newlines.
#| Can recursively find pod with C<:recurse>.
#| Can indent pod contents with C<:indent_content>.
#| Can include pod titles with C<:include_title>.
#| Can disable inlining pod formatters with C<:!inline_formatters>.
#| Can put same level items next to each other with C<:adjacent_items>.
sub join_pod_contents_of (PodOrArrayOfPod $pod, StrOrPod $thing, Bool :$recurse, |c --> Str:D) is export {
    join_pod_contents $_, |c given get_first_pod $pod, $thing, :$recurse;
}

#| Finds the first Pod using the passed C<pod> or C<name>, does so recursively if C<:recurse> is passed.
proto get_first_pod (PodOrArrayOfPod $pod, StrOrPod $thing, Bool :$recurse --> POD) is export {*}

multi get_first_pod (@pod, $pod_type, :$recurse = False --> POD) {
    if $recurse {
        @pod.map: -> POD $pod {
            if check_pod $pod, $pod_type {
                $pod;
            } elsif $pod.contents ~~ ArrayOfPod {
                $_ with samewith $pod.contents, $pod_type, :recurse;
            }
        } andthen .head;
    } else {
        @pod.first: &check_pod.assuming: *, $pod_type;
    }
}

multi get_first_pod (POD $pod, POD $pod_type, :$recurse = False --> POD) {
    samewith $pod.contents, $pod_type, :$recurse;
}

#| Finds all Pods using the passed C<pod> or C<name>, does so recursively if C<:recurse> is passed
proto get_pods (PodOrArrayOfPod $pod, StrOrPod $thing, Bool :$recurse --> List:D) is export {*}

multi get_pods (@pods, $pod_type, :$recurse = False) {
    if $recurse {
        @pods.map: -> POD $pod {
            if check_pod $pod, $pod_type {
                $pod;
            } elsif $pod.contents ~~ ArrayOfPod {
                $_ with |samewith $pod.contents, $pod_type, :recurse;
            }
        } andthen .grep(&so).List;
    } else {
        @pods.grep: &check_pod.assuming: *, $pod_type andthen .List;
    }
}

multi get_pods (POD $pod, $pod_type, :$recurse = False) {
    samewith $pod.contents, $pod_type, :$recurse;
}

#| Joins pod contents of the requested Pod type with the passed string or 2 newlines.
#| Can indent pod contents with C<:indent_content>.
#| Can include pod titles with C<:include_title>.
#| Can disable inlining pod formatters with C<:!inline_formatters>.
#| Can put same level items next to each other with C<:adjacent_items>.
sub join_pod_contents (PodOrArrayOfPod $pod, $with = "\n\n", |c --> Str:D) is export {
    if get_pod_contents $pod, |c -> @contents {
        join $with, do given @contents {
            if $_ ~~ List:D && .elems > 1 && .all ~~ List:D { .join: "\n" }
            else {
                .map: {
                    when List:D { .join: "\n" }
                    default     { $_ }
                };
            }
        }
    } else {
        '';
    }
}

#| Recursively gets the Pod contents of a Pod block as a list of (list of) strings.
#| Can indent pod contents with C<:indent_content>.
#| Can include pod titles with C<:include_title>.
#| Can disable inlining pod formatters with C<:!inline_formatters>.
#| Can put same level items next to each other with C<:adjacent_items>.
proto get_pod_contents (|) is export {*};

multi get_pod_contents (IndentablePod:D $pod,
                        |c (Bool:D :$indent_content       = False,
                            UInt:D :$indent_level is copy = 4,
                            Bool:D :$include_title        = False,
                            |)
                        --> List:D) {
    my @contents = samewith $pod.contents, |c;

    if $indent_content {
        $indent_level ×= .level - 1 when Pod::Item given $pod;

        @contents.=map: *.join("\n").&indent_content: $indent_level;
    }

    if $include_title && $pod ~~ Pod::Defn {
        @contents.unshift: (samewith($pod.term, |c), @contents.shift);
    }

    @contents.List;
}

multi get_pod_contents (SomePod:D $pod, |c (Bool:D :$include_title = False, |) --> List:D) {
    given $pod {
        when Pod::Block::Table:D {
            my List:D $contents       = .contents;
            my List:D $table_contents = $include_title ?? (.headers || Empty, |$contents) !! $contents;

            $table_contents.map({ .map({ samewith $_, |c }).List }).List;
        }
        default {
            samewith .contents, |c;
        }
    }
}

multi get_pod_contents (@pod_contents,
                        |c (Bool:D :$inline_formatters = True, Bool:D :$adjacent_items = False, |)
                        --> List:D) {
    my @contents;

    loop (my $i = 0; $i < @pod_contents; $i++) {
        if $inline_formatters and @pod_contents[$i] ~~ Pod::FormattingCode:D {
            # First observation of pod formatter
            # If the pod content before first pod formatter is a string, consider it the first index,
            # otherwise first index is the pod formatter
            my UInt:D $first_index = $i > 0 && @contents[$i - 1] ~~ Str:D ?? $i - 1 !! $i;

            while @pod_contents[$i] ~~ Pod::FormattingCode:D | Str:D {
                my Str:D $string = samewith(@pod_contents[$i], |c).join;

                # Append string to the first content
                @contents[$first_index] ~= $string;

                $i++;
            }
        } elsif $adjacent_items and @pod_contents[$i] ~~ Pod::Item:D {
            my @item_contents;

            while @pod_contents[$i] ~~ Pod::Item:D {
                @item_contents.append: samewith @pod_contents[$i], |c;

                $i++;
            }

            @contents.push: @item_contents.List;
        } else {
            given @pod_contents[$i] {
                when List:D | Pod::Block::Table:D {
                    @contents.push: samewith($_, |c).List;
                }
                default {
                    @contents.append: samewith($_, |c);
                }
            }
        }
    }

    @contents.List;
}

multi get_pod_contents (Str:D $content, | --> Str:D) {
    $content;
}

#| Returns C<True> if C<pod> matches C<pod_type>
sub check_pod (POD $pod, StrOrPod $pod_type --> Bool:D) is export(:helpers) {
    $pod | $pod.?name ~~ $pod_type;
}

#| Indents C<string> by C<indent_level>
sub indent_content (Str:D $string, UInt:D $indent_level = 4 --> Str:D) is export(:helpers) {
    $string.lines.map(' ' x $indent_level ~ *).join: "\n";
}



L<https://github.com/CIAvash/Pod-Contents/>


REPOSITORY

L<https://github.com/CIAvash/Pod-Contents/issues>


Siavash Askari Nasr - L<https://www.ciavash.name>


AUTHOR

COPYRIGHT

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/>.


LICENSE

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


unit role Pluggable;

use JSON::Fast;
use File::Find;



Pluggable - dynamically find modules or classes under a given namespace


This is a modified version orginally based on https://github.com/tony-o/perl6-pluggable.


Given a set of plugins in your library search path:


a::Plugins::Plugin1
a::Plugins::Plugin2
a::Plugins::PluginClass1::PluginClass2::Plugin3


And an invocation of Pluggable like this:


class a does Pluggable {
  method listplugins () {
    @($.plugins).map({.perl}).join("\n").say;
  }
}


When "doing" the Pluggable role, a class can use the "plugins" method:


$.plugins(:$base = Nil, :$plugins-namespace = 'Plugins', :$name-matcher = Nil)


The base namespace to look for plugins under, if not provided then the namespace from which
pluggable is invoked is used.


:$plugins-namespace (default: 'Plugins')


The name of the namespace within I<$base> that contains plugins.


If present, the name of any module found will be compared with this and only returned if they match.


In a similar fashion, the module can be used in a non-OO environment, it exports
a single sub:


plugins($base, :$plugins-namespace = 'Plugins', :$name-matcher = Nil)


The base namespace to look for plugins under. Unlike in the OO case, this is required in the procedural interface.


Released under the Artistic License 2.0 L<http://www.perlfoundation.org/artistic_license_2_0>



my sub find-modules($base, $namespace, $name-matcher) {
  my sub matching-namespaces($dist) {
    return $dist.meta.hash<provides>.keys.grep(-> $module-name {
      ($module-name.chars > "{$base}::{$namespace}".chars)
      && ($module-name.starts-with("{$base}::{$namespace}"))
      && ((!defined $name-matcher) || ($module-name ~~ $name-matcher))
    });
  }

  eager gather for $*REPO.repo-chain.grep(CompUnit::Repository::Installation | CompUnit::Repository::FileSystem) -> $repo {
    my $distributions          := $repo ~~ CompUnit::Repository::FileSystem ?? $repo.distribution !! $repo.installed;
    my $matching-distributions := $distributions.grep({ matching-namespaces($_).elems });
    my $matches-to-process     := $matching-distributions.map(-> $dist {
                                    Hash.new({
                                      distribution   => $dist,
                                      matching-specs => matching-namespaces($dist).map(-> $short-name {
                                                        CompUnit::DependencySpecification.new(
                                                          short-name      => $short-name,
                                                          version-matcher => $dist.meta<version> || True,
                                                          api-matcher     => $dist.meta<api>     || True,
                                                          auth-matcher    => $dist.meta<auth>    || True,
                                                        )
                                                      }),
                                    })
                                  });

    for @$matches-to-process -> %_ [:$distribution, :@matching-specs] {
      for @matching-specs -> $matching-spec {
        try {
          # Ideally this .need() would replace the `require` below it since the require
          # cannot take ver/api/auth attributes. However doing so causes 'no such symbol ...'
          # errors when using `::(...)`. I wonder if the way `require` is working is actually
          # a bug (namespace leaking outside of scope?)
          #$repo.need($matching-spec);
          require ::($matching-spec.short-name);
          take ::($matching-spec.short-name);
        }
      }
    }
  }
}

method plugins(:$base = Nil, :$plugins-namespace = 'Plugins', :$name-matcher = Nil) {
  my $class = "{$base.defined ?? $base !! ::?CLASS.^name}";
  return find-modules($class, $plugins-namespace, $name-matcher);
}

sub plugins($base, :$plugins-namespace = 'Plugins', :$name-matcher = Nil) is export {
  return find-modules($base, $plugins-namespace, $name-matcher);
}



Pluggable

The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


README

NAME

SYNOPSIS

FEATURES

DESCRIPTION

Object-Oriented Interface

:$base (optional)

:$plugins-namespace (default: 'Plugins')

:$name-matcher (optional)

Procedural Interface

$base (required)

:$plugins-namespace (default: 'Plugins')

:$name-matcher (optional)

DEBUGGING

LICENSE

AUTHORS

Pluggable v0.6

Authors

License

Dependencies

Test Dependencies

Provides

Documentation