=begin pod

=head1 SYNOPSIS

    # export Bin() and Script() by default.

    use FindBin;

    my $dir_from    = Bin();        # $dir_from is an IO object
    my $script_base = Script();     # $script_base is a string.

    # explicitly export only Bin() or Script().

    use FindBin :Bin;
    use FindBin :Script;

    # set verbose or resolve to True by default in the current
    # lexical scope.
    #
    # caller can examine constants
    #   MY::_FindBin-verbose-def
    #   MY::_FindBin-resolve-def
    # to determine the default.
    #
    # verbose output is sent to stderr via "note" with a 
    # leading '#'.

    use FindBin :verbose;
    use FindBin :resolve;
    use FindBin ( :verbose :resolve );

    # request the bin path with symlinks resolved
    # regardless of the default at use time.
    # Bin will have symlinks along the path resolved,
    # Script will return the basename of any resolved
    # symlink.

    my $resolved    = Bin( :resolve  );

    # determine if the current executable is running
    # from a symlinked path. stringy compare of the
    # IO objects does the right thing.

    my $dir         = Bin( :!resolve );
    my $abs         = Bin( :resolve  );

    $dir ne $abs
    and say "There is a symlink in path '$dir'";

    # make every subsequent call to Bin() default to
    # Bin( :resolve )
    # within the current lexical scope.

    use FindBin :resolve;

    # messages might be useful for dealing with
    # stray symlinks in filesystem.

    my $dir_from    = Bin( :verbose );

    # make every subsequent call to Bin() default to Bin(:verbose)
    # within the current lexical scope.

    use FindBin :verbose;

=head1 DESCRIPTION

This module is used to locate the currently running Perl program and
the diretory it is running from.

Command-line use of K<perl6 ->, K<perl6 -e> or interactive use of the
REPL will cause C<Script()> to return C<"-">, C<"-e">, or
C<"interactive"> and C<Bin()> to return C<$*CWD>.

Otherwise C<Script()> will return the basename of the running program
and C<Bin()> will return the name of the directory where the program
was run from (taken from C<$*PROGRAM> when Bin is called).

=head2 Notes:

=item Bin returns I<absolute> paths.

The IO returned by Bin will allways be an absolute (i.e.,
rooted) path via C<.absolute> or or C<.resolve>. In most cases the
I<absolute> path is more useful: people created the symlinks for a
reason; resolve is mainly useful for code performing validation or 
analysis of things like dangling links.

=item Bin returns an I<IO object>

The stringy path can be extracted calling C<~Bin()> or C<Bin.Str>.

=head2 Arguments to C<Bin()> & C<Script()>:

=item I<:resolve>

Causes C<Bin()> to return the bin value after resolving symliks with
C<.resolve> instead of C<.absolute>.

=item I<:verbose>

Turns on verbose reporting (to STDERR) for debugging purposes, 
including the path used, resolve status, and returned value.

=head2 Defaults via C<use FindBin>

The defaults for both arguments can be set in the current lexical 
context by passing the options to S<C<use FindBin>> statement. For 
example:

    # make Bin() default to Bin(:resolve)
    use FindBin :Bin, :resolve;

    # alternatively, make Bin() default to Bin(:resolve, :verbose)
    use FindBin :Bin, :resolve, :verbose;

Note that explicitly passing a C<:!resolve> or C<:!verbose> to C<Bin()>
will override these defaults:

    use FindBin :verbose;

    my $dir = Bin( :!verbose ); # runs without logging

=head2 Tests use symlinks

To see examples of using :resolve with symlinks look at the test
C<t/10-symlink.t>.

=head1 SEE ALSO

=item Perl variables C<$*PROGRAM>, C<$*PROGRAM-NAME>:

    https://docs.perl6.org/language/variables#index-entry-%24%2APROGRAM

Class which implements the dirname, basename, and absolute methods
use to determine the absolute path returned by C<Bin()>.

    https://docs.perl6.org/type/IO

=item IO I<absolute> vs. I<resolve>

L<https://docs.perl6.org/routine/absolute>
L<https://docs.perl6.org/routine/resolve>

=item https://metacpan.org/search?size=20&q=gbarr

Imitation really is the sincerest form of flattery. Kindly take a 
moment to notice how many thing that made sense and just plain
worked were contributed to Perl by Graham Barr. Then flatter him:
produce something that works equally well in Perl6.

=head1 AUTHOR

Steven Lembark <lembark@wrkhors.com>

=head1 COPYRIGHT AND LICENSE

Copyright 2018-2019 Steven Lembark

This library is free software; you can redistribute it and/or modify
it under the Artistic License 2.0 or any later version.

=end pod

