view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

        I  3 Italic
        U  4 Underline
        F  5 Flash (blink: slow)
        Q  6 Quick (blink: rapid)
        S  7 Stand out (reverse video)
        H  8 Hide (concealed)
        X  9 Cross out
        E    Erase Line

        ;    No effect
        /    Toggle foreground/background
        ^    Reset to foreground
        @    Reset index list

    If the spec includes `/`, left side is considered as foreground color
    and right side as background.  If multiple colors are given in same
    spec, all indicators are produced in the order of their presence.  As
    a result, the last one takes effect.

    Effect characters are case insensitive, and can be found anywhere and
    in any order in color spec string.  Character `;` does nothing and
    can be used just for readability, like `SD;K/544`.

    If the special reset symbol `@` is encountered, the index list is
    reset to empty at that point.  The reset symbol must be used alone and
    may not be combined with other characters.

    Example:

        RGB  6x6x6    12bit      24bit           color name
        ===  =======  =========  =============  ==================
        B    005      #00F       (0,0,255)      <blue>
         /M     /505      /#F0F   /(255,0,255)  /<magenta>
        K/W  000/555  #000/#FFF  000000/FFFFFF  <black>/<white>
        R/G  500/050  #F00/#0F0  FF0000/00FF00  <red>/<green>
        W/w  L03/L20  #333/#ccc  303030/c6c6c6  <dimgrey>/<lightgrey>

    Multiple colors can be specified separating by white space or comma,
    or by repeating options.  Those colors will be applied for each
    pattern keywords.  Next command will show word `foo` in red, `bar`
    in green and `baz` in blue.

        greple --colormap='R G B' 'foo bar baz'

        greple --cm R -e foo --cm G -e bar --cm B -e baz

    Coloring capability is implemented in [Getopt::EX::Colormap](https://metacpan.org/pod/Getopt%3A%3AEX%3A%3AColormap) module.

- **--colormap**=_field_=_spec_,...

    Another form of colormap option to specify the color for fields:

        FILE      File name
        LINE      Line number
        TEXT      Unmatched normal text
        BLOCKEND  Block end mark
        PROGRESS  Progress status with -dnf option

    The `BLOCKEND` mark is colored with `E` effect provided by
    [Getopt::EX](https://metacpan.org/pod/Getopt%3A%3AEX) module, which allows to fill up the line with background
    color.  This effect uses irregular escape
    sequence, and you may need to define `LESSANSIENDCHARS` environment
    as "mK" to see the result with [less](https://metacpan.org/pod/less) command.

- **--colormap**=`&func`
- **--colormap**=`sub{...}`

    You can also set the name of perl subroutine name or definition to be
    called handling matched words.  Target word is passed as variable
    `$_`, and the return value of the subroutine will be displayed.

    Next command convert all words in C comment to upper case.

        greple --all '/\*(?s:.*?)\*/' --cm 'sub{uc}'

    You can quote matched string instead of coloring (this emulates
    deprecated option `--quote`):

        greple --cm 'sub{"<".$_.">"}' ...

    It is possible to use this definition with field names.  Next example
    print line numbers in seven digits.

        greple -n --cm 'LINE=sub{s/(\d+)/sprintf("%07d",$1)/e;$_}'

    Experimentally, function can be combined with other normal color
    specifications.  Also the form `&func;` can be repeated.

        greple --cm 'BF/544;sub{uc}'

        greple --cm 'R;&func1;&func2;&func3'

    When color for 'TEXT' field is specified, whole text including matched
    part is passed to the function, exceptionally.  It is not recommended
    to use user defined function for 'TEXT' field.

- **--colorsub**=`...`, **--cs**=`...`

    `--colorsub` or `--cs` is a shortcut for subroutine colormap.  It
    simply enclose the argument by `sub{ ... }` expression.  So

        greple --cm 'sub{uc}'

    can be written as simple as this.

        greple --cs uc

    You can not use this option for labeled color.

- **--\[no\]colorful**

    Shortcut for `--colormap`='`RD GD BD CD MD YD`' in ANSI 16 colors
    mode, and `--colormap`='`D/544 D/454 D/445 D/455 D/454 D/554`' and
    other combination of 3, 4, 5 for 256 colors mode.  Enabled by default.

    When single pattern is specified, first color in colormap is used for
    the pattern.  If multiple patterns and multiple colors are specified,
    each pattern is colored with corresponding color cyclically.

    Option `--regioncolor` and `--colorindex` change this behavior.

README.md  view on Meta::CPAN

    - **begin**

        (Default 0) When `--begin` function died with `/^SKIP/i` message,
        the file is skipped without any notice.  Enables this to see the dying
        message.

    - **all**

        Set same value for all types.

- **--alert** \[ `size`=#, `time`=# \]

    Set alert parameter for large file.  **Greple** scans whole file
    content to know line borders, and it takes several seconds or more if
    it contains large number of lines.

    By default, if the target file contains more than **512 \* 1024
    characters** (_size_), **2 seconds** timer will start (_time_).  Alert
    message is shown when the timer expired.

    To disable this alert, set the size as zero:

        --alert size=0

- **-Mdebug**, **-d**_x_

    Debug option is described in [App::Greple::debug](https://metacpan.org/pod/App%3A%3AGreple%3A%3Adebug) module.

# ENVIRONMENT and STARTUP FILE

- **GREPLEOPTS**

    Environment variable GREPLEOPTS is used as a default options.  They
    are inserted before command line options.

- **GREPLE\_NORC**

    If set non-empty string, startup file `~/.greplerc` is not processed.

- **DEBUG\_GETOPT**

    Enable [Getopt::Long](https://metacpan.org/pod/Getopt%3A%3ALong) debug option.

- **DEBUG\_GETOPTEX**

    Enable [Getopt::EX](https://metacpan.org/pod/Getopt%3A%3AEX) debug option.

- **NO\_COLOR**

    If true, all coloring capability with ANSI terminal sequence is
    disabled.  See [https://no-color.org/](https://no-color.org/).

Before starting execution, **greple** reads the file named `.greplerc`
on user's home directory.  Following directives can be used.

- **option** _name_ string

    Argument _name_ of **option** directive is user defined option name.
    The rest are processed by `shellwords` routine defined in
    Text::ParseWords module.  Be sure that this module sometimes requires
    escape backslashes.

    Any kind of string can be used for option name but it is not combined
    with other options.

        option --fromcode --outside='(?s)\/\*.*?\*\/'
        option --fromcomment --inside='(?s)\/\*.*?\*\/'

    If the option named **default** is defined, it will be used as a
    default option.

    For the purpose to include following arguments within replaced
    strings, two special notations can be used in option definition.
    String `$<n>` is replaced by the _n_th argument after the
    substituted option, where _n_ is number start from one.  String
    `$<shift>` is replaced by following command line argument and
    the argument is removed from option list.

    For example, when

        option --line --le &line=$<shift>

    is defined, command

        greple --line 10,20-30,40

    will be evaluated as this:

        greple --le &line=10,20-30,40

- **expand** _name_ _string_

    Define local option _name_.  Command **expand** is almost same as
    command **option** in terms of its function.  However, option defined
    by this command is expanded in, and only in, the process of
    definition, while option definition is expanded when command arguments
    are processed.

    This is similar to string macro defined by following **define**
    command.  But macro expansion is done by simple string replacement, so
    you have to use **expand** to define option composed by multiple
    arguments.

- **define** _name_ string

    Define macro.  This is similar to **option**, but argument is not
    processed by _shellwords_ and treated just a simple text, so
    meta-characters can be included without escape.  Macro expansion is
    done for option definition and other macro definition.  Macro is not
    evaluated in command line option.  Use option directive if you want to
    use in command line,

        define (#kana) \p{InKatakana}
        option --kanalist --nocolor -o --join --re '(#kana)+(\n(#kana)+)*'
        help   --kanalist List up Katakana string

- **help** _name_

    If **help** directive is used for same option name, it will be printed
    in usage message.  If the help message is `ignore`, corresponding
    line won't show up in the usage.

- **builtin** _spec_ _variable_

    Define built-in option which should be processed by option parser.
    Arguments are assumed to be [Getopt::Long](https://metacpan.org/pod/Getopt%3A%3ALong) style spec, and
    _variable_ is string start with `$`, `@` or `%`.  They will be
    replaced by a reference to the object which the string represent.

    See **pgp** module for example.

- **autoload** _module_ _options_ ...

    Define module which should be loaded automatically when specified
    option is found in the command arguments.

    For example,

        autoload -Mdig --dig --git

    replaces option "`--dig`" to "`-Mdig --dig`", so that **dig** module
    is loaded before processing `--dig` option.

Environment variable substitution is done for string specified by
`option` and `define` directives.  Use Perl syntax **$ENV{NAME}** for
this purpose.  You can use this to make a portable module.

When **greple** found `__PERL__` line in `.greplerc` file, the rest
of the file is evaluated as a Perl program.  You can define your own
subroutines which can be used by `--inside`/`--outside`,
`--include`/`--exclude`, `--block` options.

For those subroutines, file content will be provided by global
variable `$_`.  Expected response from the subroutine is the list of
array references, which is made up by start and end offset pairs.

For example, suppose that the following function is defined in your
`.greplerc` file.  Start and end offset for each pattern match can be
taken as array element `$-[0]` and `$+[0]`.

    __PERL__
    sub odd_line {
        my @list;
        my $i;
        while (/.*\n/g) {
            push(@list, [ $-[0], $+[0] ]) if ++$i % 2;
        }
        @list;