'\" te
.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CPANPLUS::Internals::Source 3"
.TH CPANPLUS::Internals::Source 3 "2012-11-03" "perl v5.12.5" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CPANPLUS::Internals::Source
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    ### lazy load author/module trees ###
\&
\&    $cb\->_author_tree;
\&    $cb\->_module_tree;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
CPANPLUS::Internals::Source controls the updating of source files and
the parsing of them into usable module/author trees to be used by
\&\f(CW\*(C`CPANPLUS\*(C'\fR.
.PP
Functions exist to check if source files are still \f(CW\*(C`good to use\*(C'\fR as
well as update them, and then parse them.
.PP
The flow looks like this:
.PP
.Vb 10
\&    $cb\->_author_tree || $cb\->_module_tree
\&        $cb\->_check_trees
\&            $cb\->_\|_check_uptodate
\&                $cb\->_update_source
\&            $cb\->_\|_update_custom_module_sources 
\&                $cb\->_\|_update_custom_module_source
\&        $cb\->_build_trees
\&            ### engine methods
\&            {   $cb\->_init_trees;
\&                $cb\->_standard_trees_completed
\&                $cb\->_custom_trees_completed
\&            }                
\&            $cb\->_\|_create_author_tree
\&                ### engine methods
\&                { $cb\->_add_author_object }
\&            $cb\->_\|_create_module_tree
\&                $cb\->_\|_create_dslip_tree
\&                ### engine methods
\&                { $cb\->_add_module_object }
\&            $cb\->_\|_create_custom_module_entries                    
\&
\&    $cb\->_dslip_defs
.Ve
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$cb\->_build_trees( uptodate => \s-1BOOL\s0, [use_stored => \s-1BOOL\s0, path => $path, verbose => \s-1BOOL\s0] )"
.el .SS "\f(CW$cb\fP\->_build_trees( uptodate => \s-1BOOL\s0, [use_stored => \s-1BOOL\s0, path => \f(CW$path\fP, verbose => \s-1BOOL\s0] )"
.IX Subsection "$cb->_build_trees( uptodate => BOOL, [use_stored => BOOL, path => $path, verbose => BOOL] )"
This method rebuilds the author\- and module-trees from source.
.PP
It takes the following arguments:
.IP "uptodate" 4
.IX Item "uptodate"
Indicates whether any on disk caches are still ok to use.
.IP "path" 4
.IX Item "path"
The absolute path to the directory holding the source files.
.IP "verbose" 4
.IX Item "verbose"
A boolean flag indicating whether or not to be verbose.
.IP "use_stored" 4
.IX Item "use_stored"
A boolean flag indicating whether or not it is ok to use previously
stored trees. Defaults to true.
.PP
Returns a boolean indicating success.
.ie n .SS "$cb\->_check_trees( [update_source => \s-1BOOL\s0, path => \s-1PATH\s0, verbose => \s-1BOOL\s0] )"
.el .SS "\f(CW$cb\fP\->_check_trees( [update_source => \s-1BOOL\s0, path => \s-1PATH\s0, verbose => \s-1BOOL\s0] )"
.IX Subsection "$cb->_check_trees( [update_source => BOOL, path => PATH, verbose => BOOL] )"
Retrieve source files and return a boolean indicating whether or not
the source files are up to date.
.PP
Takes several arguments:
.IP "update_source" 4
.IX Item "update_source"
A flag to force re-fetching of the source files, even
if they are still up to date.
.IP "path" 4
.IX Item "path"
The absolute path to the directory holding the source files.
.IP "verbose" 4
.IX Item "verbose"
A boolean flag indicating whether or not to be verbose.
.PP
Will get information from the config file by default.
.ie n .SS "$cb\->_\|_check_uptodate( file => $file, name => $name, [update_source => \s-1BOOL\s0, verbose => \s-1BOOL\s0] )"
.el .SS "\f(CW$cb\fP\->_\|_check_uptodate( file => \f(CW$file\fP, name => \f(CW$name\fP, [update_source => \s-1BOOL\s0, verbose => \s-1BOOL\s0] )"
.IX Subsection "$cb->__check_uptodate( file => $file, name => $name, [update_source => BOOL, verbose => BOOL] )"
\&\f(CW\*(C`_\|_check_uptodate\*(C'\fR checks if a given source file is still up-to-date
and if not, or when \f(CW\*(C`update_source\*(C'\fR is true, will re-fetch the source
file.
.PP
Takes the following arguments:
.IP "file" 4
.IX Item "file"
The source file to check.
.IP "name" 4
.IX Item "name"
The internal shortcut name for the source file (used for config
lookups).
.IP "update_source" 4
.IX Item "update_source"
Flag to force updating of sourcefiles regardless.
.IP "verbose" 4
.IX Item "verbose"
Boolean to indicate whether to be verbose or not.
.PP
Returns a boolean value indicating whether the current files are up
to date or not.
.ie n .SS "$cb\->_update_source( name => $name, [path => $path, verbose => \s-1BOOL\s0] )"
.el .SS "\f(CW$cb\fP\->_update_source( name => \f(CW$name\fP, [path => \f(CW$path\fP, verbose => \s-1BOOL\s0] )"
.IX Subsection "$cb->_update_source( name => $name, [path => $path, verbose => BOOL] )"
This method does the actual fetching of source files.
.PP
It takes the following arguments:
.IP "name" 4
.IX Item "name"
The internal shortcut name for the source file (used for config
lookups).
.IP "path" 4
.IX Item "path"
The full path where to write the files.
.IP "verbose" 4
.IX Item "verbose"
Boolean to indicate whether to be verbose or not.
.PP
Returns a boolean to indicate success.
.ie n .SS "$cb\->_\|_create_author_tree([path => $path, uptodate => \s-1BOOL\s0, verbose => \s-1BOOL\s0])"
.el .SS "\f(CW$cb\fP\->_\|_create_author_tree([path => \f(CW$path\fP, uptodate => \s-1BOOL\s0, verbose => \s-1BOOL\s0])"
.IX Subsection "$cb->__create_author_tree([path => $path, uptodate => BOOL, verbose => BOOL])"
This method opens a source files and parses its contents into a
searchable author-tree or restores a file-cached version of a
previous parse, if the sources are uptodate and the file-cache exists.
.PP
It takes the following arguments:
.IP "uptodate" 4
.IX Item "uptodate"
A flag indicating whether the file-cache is uptodate or not.
.IP "path" 4
.IX Item "path"
The absolute path to the directory holding the source files.
.IP "verbose" 4
.IX Item "verbose"
A boolean flag indicating whether or not to be verbose.
.PP
Will get information from the config file by default.
.PP
Returns a tree on success, false on failure.
.ie n .SS "$cb\->_create_mod_tree([path => $path, uptodate => \s-1BOOL\s0, verbose => \s-1BOOL\s0])"
.el .SS "\f(CW$cb\fP\->_create_mod_tree([path => \f(CW$path\fP, uptodate => \s-1BOOL\s0, verbose => \s-1BOOL\s0])"
.IX Subsection "$cb->_create_mod_tree([path => $path, uptodate => BOOL, verbose => BOOL])"
This method opens a source files and parses its contents into a
searchable module-tree or restores a file-cached version of a
previous parse, if the sources are uptodate and the file-cache exists.
.PP
It takes the following arguments:
.IP "uptodate" 4
.IX Item "uptodate"
A flag indicating whether the file-cache is up-to-date or not.
.IP "path" 4
.IX Item "path"
The absolute path to the directory holding the source files.
.IP "verbose" 4
.IX Item "verbose"
A boolean flag indicating whether or not to be verbose.
.PP
Will get information from the config file by default.
.PP
Returns a tree on success, false on failure.
.ie n .SS "$cb\->_\|_create_dslip_tree([path => $path, uptodate => \s-1BOOL\s0, verbose => \s-1BOOL\s0])"
.el .SS "\f(CW$cb\fP\->_\|_create_dslip_tree([path => \f(CW$path\fP, uptodate => \s-1BOOL\s0, verbose => \s-1BOOL\s0])"
.IX Subsection "$cb->__create_dslip_tree([path => $path, uptodate => BOOL, verbose => BOOL])"
This method opens a source files and parses its contents into a
searchable dslip-tree or restores a file-cached version of a
previous parse, if the sources are uptodate and the file-cache exists.
.PP
It takes the following arguments:
.IP "uptodate" 4
.IX Item "uptodate"
A flag indicating whether the file-cache is uptodate or not.
.IP "path" 4
.IX Item "path"
The absolute path to the directory holding the source files.
.IP "verbose" 4
.IX Item "verbose"
A boolean flag indicating whether or not to be verbose.
.PP
Will get information from the config file by default.
.PP
Returns a tree on success, false on failure.
.ie n .SS "$cb\->_dslip_defs ()"
.el .SS "\f(CW$cb\fP\->_dslip_defs ()"
.IX Subsection "$cb->_dslip_defs ()"
This function returns the definition structure (\s-1ARRAYREF\s0) of the
dslip tree.
.ie n .SS "$file = $cb\->_add_custom_module_source( uri => \s-1URI\s0, [verbose => \s-1BOOL\s0] );"
.el .SS "\f(CW$file\fP = \f(CW$cb\fP\->_add_custom_module_source( uri => \s-1URI\s0, [verbose => \s-1BOOL\s0] );"
.IX Subsection "$file = $cb->_add_custom_module_source( uri => URI, [verbose => BOOL] );"
Adds a custom source index and updates it based on the provided \s-1URI\s0.
.PP
Returns the full path to the index file on success or false on failure.
.ie n .SS "$index = $cb\->_\|_custom_module_source_index_file( uri => $uri );"
.el .SS "\f(CW$index\fP = \f(CW$cb\fP\->_\|_custom_module_source_index_file( uri => \f(CW$uri\fP );"
.IX Subsection "$index = $cb->__custom_module_source_index_file( uri => $uri );"
Returns the full path to the encoded index file for \f(CW$uri\fR, as used by
all \f(CW\*(C`custom module source\*(C'\fR routines.
.ie n .SS "$file = $cb\->_remove_custom_module_source( uri => \s-1URI\s0, [verbose => \s-1BOOL\s0] );"
.el .SS "\f(CW$file\fP = \f(CW$cb\fP\->_remove_custom_module_source( uri => \s-1URI\s0, [verbose => \s-1BOOL\s0] );"
.IX Subsection "$file = $cb->_remove_custom_module_source( uri => URI, [verbose => BOOL] );"
Removes a custom index file based on the \s-1URI\s0 provided.
.PP
Returns the full path to the index file on success or false on failure.
.ie n .SS "%files = $cb\->_\|_list_custom_module_sources"
.el .SS "\f(CW%files\fP = \f(CW$cb\fP\->_\|_list_custom_module_sources"
.IX Subsection "%files = $cb->__list_custom_module_sources"
This method scans the 'custom\-sources' directory in your base directory
for additional sources to include in your module tree.
.PP
Returns a list of key value pairs as follows:
.PP
.Vb 1
\&  /full/path/to/source/file%3Fencoded => http://decoded/mirror/path
.Ve
.ie n .SS "$bool = $cb\->_\|_update_custom_module_sources( [verbose => \s-1BOOL\s0] );"
.el .SS "\f(CW$bool\fP = \f(CW$cb\fP\->_\|_update_custom_module_sources( [verbose => \s-1BOOL\s0] );"
.IX Subsection "$bool = $cb->__update_custom_module_sources( [verbose => BOOL] );"
Attempts to update all the index files to your custom module sources.
.PP
If the index is missing, and it's a \f(CW\*(C`file://\*(C'\fR uri, it will generate
a new local index for you.
.PP
Return true on success, false on failure.
.ie n .SS "$ok = $cb\->_\|_update_custom_module_source"
.el .SS "\f(CW$ok\fP = \f(CW$cb\fP\->_\|_update_custom_module_source"
.IX Subsection "$ok = $cb->__update_custom_module_source"
Attempts to update all the index files to your custom module sources.
.PP
If the index is missing, and it's a \f(CW\*(C`file://\*(C'\fR uri, it will generate
a new local index for you.
.PP
Return true on success, false on failure.
.ie n .SS "$bool = $cb\->_\|_write_custom_module_index( path => /path/to/packages, [to => /path/to/index/file, verbose => \s-1BOOL\s0] )"
.el .SS "\f(CW$bool\fP = \f(CW$cb\fP\->_\|_write_custom_module_index( path => /path/to/packages, [to => /path/to/index/file, verbose => \s-1BOOL\s0] )"
.IX Subsection "$bool = $cb->__write_custom_module_index( path => /path/to/packages, [to => /path/to/index/file, verbose => BOOL] )"
Scans the \f(CW\*(C`path\*(C'\fR you provided for packages and writes an index with all 
the available packages to \f(CW\*(C`$path/packages.txt\*(C'\fR. If you'd like the index
to be written to a different file, provide the \f(CW\*(C`to\*(C'\fR argument.
.PP
Returns true on success and false on failure.
.ie n .SS "$bool = $cb\->_\|_create_custom_module_entries( [verbose => \s-1BOOL\s0] )"
.el .SS "\f(CW$bool\fP = \f(CW$cb\fP\->_\|_create_custom_module_entries( [verbose => \s-1BOOL\s0] )"
.IX Subsection "$bool = $cb->__create_custom_module_entries( [verbose => BOOL] )"
Creates entries in the module tree based upon the files as returned
by \f(CW\*(C`_\|_list_custom_module_sources\*(C'\fR.
.PP
Returns true on success, false on failure.


.\" Oracle has added the ARC stability level to this manual page
.SH ATTRIBUTES
See
.BR attributes (5)
for descriptions of the following attributes:
.sp
.TS
box;
cbp-1 | cbp-1
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE 
=
Availability	runtime/perl-512
=
Stability	Uncommitted
.TE 
.PP

.SH NOTES

.\" Oracle has added source availability information to this manual page
This software was built from source available at https://java.net/projects/solaris-userland.  The original community source was downloaded from  http://www.cpan.org/src/5.0/perl-5.12.5.tar.bz2

Further information about this software can be found on the open source community website at http://www.perl.org/.