.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Class::Forward 3pm"
.TH Class::Forward 3pm "2018-01-27" "perl v5.26.1" "User Contributed Perl Documentation"
.\" 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"
Class::Forward \- Namespace Dispatch and Resolution
.SH "VERSION"
.IX Header "VERSION"
version 0.100006
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Class::Forward;
\&
\&    # create a resolution object
\&    my $res = Class::Forward\->new(namespace => \*(AqMyApp\*(Aq);
\&
\&    # returns MyApp::Data
\&    say $res\->forward(\*(Aqdata\*(Aq);
\&
\&    # returns a MyApp::Data instance
\&    my $data  = $res\->forward(\*(Aqdata.new\*(Aq);
\&
\&    # returns the string /my_app/data
\&    my $string = $res\->reverse(\*(Aqdata.new\*(Aq);
\&
\&    # returns MyApp::Data
\&    say $res\->forward($string);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Class::Forward is designed to resolve Perl namespaces from shorthand (which is
simply a file-path-like specification). Class::Forward can also be used to
dispatch method calls using said shorthand. See the following exported
functions for examples on how this can be used.
.SH "EXPORTS"
.IX Header "EXPORTS"
.SS "clsf"
.IX Subsection "clsf"
The exported function clsf is responsible for resolving your shorthand. The
following is an example of how it functions:
.PP
.Vb 1
\&    package App::Store;
\&
\&    use CGI;
\&    use Class::Forward;
\&
\&    clsf;                             # returns App::Store
\&    clsf \*(Aq./user\*(Aq;                    # returns App::Store::User
\&    clsf \*(Aq./user.new\*(Aq, name => \*(AqN30\*(Aq; # return a new App::Store::User object
\&    clsf \*(Aq./user_profile.new\*(Aq;        # ... App::Store::UserProfile object
\&    clsf \*(Aq../user\*(Aq;                   # returns App::User
\&    clsf \*(Aq//\*(Aq;                        # returns App; (top of the calling class)
\&    clsf \*(Aq//.new\*(Aq;                    # returns a new App object
\&    clsf \*(Aq//view\*(Aq;                    # ... returns App::View
\&    clsf \*(Aq//view.new\*(Aq;                # ... returns a new App::View object
\&    clsf \*(Aq//view.new.render\*(Aq;         # ... dispatches methods in succession
\&    clsf \*(Aqcgi\*(Aq;                       # returns App::Store::Cgi
\&    clsf \*(Aq/cgi\*(Aq;                      # returns Cgi (or CGI if already loaded)
\&
\&    1;
.Ve
.PP
The clsf function takes two arguments, the shorthand to be translated, and an
optional list of arguments to be passed to the last method appended to the
shorthand.
.SS "clsr"
.IX Subsection "clsr"
The exported function clsr is responsible for resolving your shorthand. The
following is an example of how it functions:
.PP
.Vb 1
\&    package App::Store;
\&
\&    use CGI;
\&    use Class::Forward;
\&
\&    clsr;                             # returns /app/store
\&    clsr \*(Aq./user\*(Aq;                    # returns /app/store/user
\&    clsr \*(Aq./user.new\*(Aq, name => \*(AqN30\*(Aq; # returns /app/store/user
\&    clsr \*(Aq./user_profile\*(Aq;            # returns /app/store/user_profile
\&    clsr \*(Aq../user\*(Aq;                   # returns /app/user
\&    clsr \*(Aq//\*(Aq;                        # returns /app
\&    clsr \*(Aq//.new\*(Aq;                    # returns /app
\&    clsr \*(Aq//view\*(Aq;                    # returns /app/view
\&    clsr \*(Aq//view.new\*(Aq;                # returns /app/view
\&    clsr \*(Aq//view.new.render\*(Aq;         # returns /app/view
\&    clsr \*(Aqcgi\*(Aq;                       # returns /app/store/cgi
\&    clsr \*(Aq/cgi\*(Aq;                      # returns /cgi
\&
\&    1;
.Ve
.PP
The clsr function takes three arguments, the shorthand to be translated
(required), the offset (optional level of namespace nodes to omit
left-to-right), and the delimiter to be used to generate the resulting path
(defaults to forward-slash).
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
The new method is used to instantiate a new instance.
.SS "namespace"
.IX Subsection "namespace"
The namespace method is used to get/set the root namespace used as an anchor for
all resolution requests.
.PP
.Vb 1
\&    my $namespace = $self\->namespace(\*(AqMyApp\*(Aq);
.Ve
.SS "forward"
.IX Subsection "forward"
The forward (or forward_lookup) method is used to resolve Perl namespaces from
path-like shorthand.
.PP
.Vb 3
\&    say $self\->forward(\*(Aqexample\*(Aq);
\&    # given a default namespace of MyApp
\&    # prints MyApp::Example
.Ve
.SS "reverse"
.IX Subsection "reverse"
The reverse method (or reverse_lookup) is used to generate path-like shorthand
from Perl namespaces.
.PP
.Vb 3
\&    say $self\->reverse(\*(AqSimple::Example\*(Aq);
\&    # given a default namespace of MyApp
\&    # prints /my_app/simple/example
\&
\&    say $self\->reverse(\*(AqSimple::Example\*(Aq, 1);
\&    # given a default namespace of MyApp
\&    # prints simple/example
\&
\&    say $self\->reverse(\*(AqSimple::Example\*(Aq, 1, \*(Aq_\*(Aq);
\&    # given a default namespace of MyApp
\&    # prints simple_example
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Class::Forward was designed to provide shorthand and easy access to class
namespaces in an environment where you're dealing with a multitude of long
well-named classes. In that vein, it provides an alternative to modules like
aliased, aliased::factory, as, and the like, and also modules like
Namespace::Dispatch which are similar enough to be mentioned but really
address a completely different issue.
.SH "AUTHOR"
.IX Header "AUTHOR"
Al Newkirk <anewkirk@ana.io>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Al Newkirk.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.