NAME

Pod::Weaver::Plugin::Include::Finder - Finds source Pods in .pod files or modules.

VERSION

version v0.1.9

SYNOPSIS

    use Pod::Weaver::Plugin::Include::Finder;
    
    my $finder = Pod::Weaver::Plugin::Include::Finder->new;
    my $template = $finder->get_template(
        template => 'tmplName',
        source => 'source.pod',
    );

DESCRIPTION

This module loads sources, parses them and caches templates found.

ATTRIBUTES

cache

Cache of templates by sources. Hash of hashes where first level keys are sources by their full file names; and second level keys are template names. Each cache entry is an array of Pod nodes.

maps

Mapping of short names into full path names. Short names are either aliases or what is used with a =include command. For example:

    =srcAlias alias Some::Module
    =include template@templates/src.pod

With these commands the map will contain keys alias and templates/src.pod.

callerPlugin

Back reference to a Pod::Weaver::Plugin::Include instance.

pod_path

List of entries from pod_path configuration variable.

METHODS

find_source( $source )

Takes a short source name (not alias!) and returns full path name for it or undef if not found.

Successful search is stored into maps attribute.

register_alias( $alias, $source )

Finds out the full path name for $source and stores a new entry for $alias in maps attribute. Does nothing if source is not found.

NOTE: This method will result in two maps entries: one for the $source and one for the $alias.

Returns full path name of the $source.

parse_tmpl( $str )

Parses argument of =tmpl command. Returns a profile hash with two keys:

hidden

Boolean, true if template is declared hidden.

name

Template name.

load_file( $file )

Loads and parses a source file defined by $file. The result is stored into cache.

Returns true if file has been successully read by Pod::Elemental.

get_template( %opts )

Returns a cached template. %opts profile can have two keys:

template

Template name

source

Source in short form including aliases.

If a template is missing in the cache then tries to load_file().

Returns undef if failed.

init_cache

Initializer for cache attribute.

init_maps

Initilizer for maps attribute.

init_pod_path

Initializer for pod_path attribute.

init_logger

Initializer for logger attribute. Takes logger object either from callerPlugin or creates a new one.

PRIVATE ATTRIBUTES

_tmplSource, _tmplName, _tmplContent

Solely for use by load_file() and _store_template() methods.

PRIVATE METHODS

_store_template

Records a new template into the cache.

AUTHOR

Vadim Belman <vrurg@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Vadim Belman.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Pod::Weaver::Plugin::Include

perl -MCPAN -e shell
install Pod::Weaver::Plugin::Include