txt: ## dist_cpan-LEMBARK-FindBin.md
  # 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;
  
  ```
  
  # DESCRIPTION
  
  This module is used to locate the currently running Raku program and the diretory it is running from.
  
  Command-line use of raku -, raku -e or interactive use of the REPL will cause `Script()` to return `"-"`, `"-e"`, or `"interactive"` and `Bin()` to return `$*CWD`.
  
  Otherwise `Script()` will return the basename of the running program and `Bin()` will return the name of the directory where the program was run from (taken from `$*PROGRAM` when Bin is called).
  
  ## Notes:
  
  * Bin returns *absolute* paths.
  
  The IO returned by Bin will allways be an absolute (i.e., rooted) path via `.absolute` or or `.resolve`. In most cases the *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.
  
  * Bin returns an *IO object*
  
  The stringy path can be extracted calling `~Bin()` or `Bin.Str`.
  
  ## Arguments to `Bin()` & `Script()`:
  
  * *:resolve*
  
  Causes `Bin()` to return the bin value after resolving symliks with `.resolve` instead of `.absolute`.
  
  * *:verbose*
  
  Turns on verbose reporting (to STDERR) for debugging purposes, including the path used, resolve status, and returned value.
  
  ## Defaults via `use FindBin`
  
  The defaults for both arguments can be set in the current lexical context by passing the options to `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 `:!resolve` or `:!verbose` to `Bin()` will override these defaults:
  
  ```
  use FindBin :verbose;
  
  my $dir = Bin( :!verbose ); # runs without logging
  
  ```
  
  ## Tests use symlinks
  
  To see examples of using :resolve with symlinks look at the test `t/10-symlink.t`.
  
  # SEE ALSO
  
  * Raku variables `$*PROGRAM`, `$*PROGRAM-NAME`:
  
    <https://docs.raku.org/language/variables#index-entry-%24%2APROGRAM>
  
  Class which implements the dirname, basename, and absolute methods use to determine the absolute path returned by `Bin()`.
  
  ```
  https://docs.raku.org/type/IO
  
  ```
  
  * IO *absolute* vs. *resolve*
  
  <https://docs.raku.org/routine/absolute> <https://docs.raku.org/routine/resolve>
  
  * <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 Raku.
  
  # AUTHOR
  
  Steven Lembark [lembark@wrkhors.com](mailto:lembark@wrkhors.com)
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2018-2020 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.
  