### ----------------------------------------------------
### -- App::Rak
### -- Licenses: Artistic-2.0
### -- Authors: Elizabeth Mattijsen
### -- File: resources/help/special.txt
### ----------------------------------------------------
Special options:
‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒‒

--checkout=string

Helper function for the busy developer who has a large number of
git branches to handle.  Takes the specified string, searches the
available branches in the current directory, and will checkout
the one if there is a single match.  Presents the matching branches
if there is more than one.  Will checkout branch "main" if "master"
was specified if there is no branch named "master", and vice-versa.
Branches need not have been checked out locally yet.

--edit[=editor]

Take the search result as positions in the code to go edit.  If no
specific editor is specified, will assume what is specified in the
EDITOR environment variable.  If no editor specification can be
found, will assume "vim" as the editor.

Can be used in conjuction with --find to edit files of which the
name matches the pattern.

--vimgrep

Take the search result as positiuons in the code to go edit from
within "vim" using the :vimgrep option.

--backtrace

Flag.  When specified with a True value, will interpret either standard
input, or a single file, as a Raku backtrace.  And produce a result
containing the lines of source code from that backtrace.  Can be used
together with --context, --before-context, --after-context, --edit and
 --vimgrep.  Any pattern specification will only be used for highlighting.
If *not* used in combination with --edit or --vimgrep, will assume a
context of 2 lines.

Examples:
# look at source of a stacktrace after running script
$ raku script 2>&1 | rak --backtrace

# inspect the source of a stacktrace in an editor
$ raku script 2>&1 | rak --backtrace --edit

# inspect a backtrace stored in a file
$ rak --backtrace filename

--execute-raku[=code]

Flag or code specification.  When specified with a True value, will
use the pattern as the name of a script to execute.  If code is specified
will execute that code.  If the code consists of "-", then will read code
from STDIN to execute.  Any execution error's backtrace will be used
to produce a result with the lines of source code of that backtrace.
Can be used together with --context, --before-context, --after-context,
 --edit and --vimgrep.  If *not* used in combination with --edit or --vimgrep,
will assume a context of 2 lines.  If --verbose is specified, will try to
create an extended (--ll-exception) backtrace.

Examples:
# look at source of a stacktrace after running script
$ rak --execute-raku script

# inspect the source of a stacktrace in an editor
$ rak --execute-raku script --edit

# inspect a backtrace from execution of code read from STDIN
$ cat script | rak --execute-raku=-

--sourcery

Mainly intended for Raku Programming Language core developers.
If specified, indicates that the pattern should be interpreted
as code specifying a simple call to a subroutine, or a simple
call to a method, optionally with arguments.  The search result
will then contain the source locations of subroutine / method
that is expected to be able to handle that call.  Compatible
with the --edit, --vimgrep and the implicit per-line option.

Example:
# edit the location(s) of the "say" sub handling a single string
$ rak --sourcery 'say "foo"' --edit


