jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update nimgrep documentation (#17415)

Browse source 
* update nimgrep documentation

* Update doc/nimgrep_cmdline.txt

Co-authored-by: Andreas Rumpf <rumpf_a@web.de>
This commit is contained in:
Andrey Makarov 2021-03-23 20:12:27 +03:00 • committed by GitHub
commit 368422c219
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 157 additions and 124 deletions
Download patch file Download diff file Expand all files Collapse all files

66
doc/nimgrep.rst
View file

@ -4,17 +4,20 @@
nimgrep User's manual nimgrep User's manual
========================= =========================
.. default-role:: literal
:Author: Andreas Rumpf :Author: Andreas Rumpf
:Version: 0.9 :Version: 1.6.0
.. contents::
Nimgrep is a command line tool for search&replace tasks. It can search for Nimgrep is a command line tool for search and replace tasks. It can search for
regex or peg patterns and can search whole directories at once. User regex or peg patterns and can search whole directories at once. User
confirmation for every single replace operation can be requested. confirmation for every single replace operation can be requested.
Nimgrep has particularly good support for Nim's Nimgrep has particularly good support for Nim's
eccentric *style insensitivity*. Apart from that it is a generic text eccentric *style insensitivity* (see option `-y` below).
manipulation tool. Apart from that it is a generic text manipulation tool.
Installation Installation
@ -30,23 +33,38 @@ And copy the executable somewhere in your `$PATH`.
Command line switches Command line switches
===================== =====================
Usage: .. include:: nimgrep_cmdline.txt
nimgrep [options] [pattern] [replacement] (file/directory)*
Options: Examples
--find, -f find the pattern (default) ========
--replace, -r replace the pattern
--peg pattern is a peg All examples below use default PCRE Regex patterns:
--re pattern is a regular expression (default); extended
syntax for the regular expression is always turned on + To search recursively in Nim files using style-insensitive identifiers::
--recursive process directories recursively
--confirm confirm each occurrence/replacement; there is a chance --recursive --ext:'nim|nims' --ignoreStyle
to abort any time without touching the file # short: -r --ext:'nim|nims' -y
--stdin read pattern from stdin (to avoid the shell's confusing
quoting rules) .. Note:: we used `'` quotes to avoid special treatment of `|` symbol
--word, -w the match should have word boundaries (buggy for pegs!) for shells like Bash
--ignoreCase, -i be case insensitive
--ignoreStyle, -y be style insensitive + To exclude version control directories (Git, Mercurial=hg, Subversion=svn)
--ext:EX1|EX2|... only search the files with the given extension(s) from the search::
--verbose be verbose: list every processed file
--help, -h shows this help --excludeDir:'^\.git$' --excludeDir:'^\.hg$' --excludeDir:'^\.svn$'
--version, -v shows the version # short: --ed:'^\.git$' --ed:'^\.hg$' --ed:'^\.svn$'
+ To search only in paths containing the `tests` sub-directory recursively::
--recursive --includeDir:'(^|/)tests($|/)'
# short: -r --id:'(^|/)tests($|/)'
.. Attention:: note the subtle difference between `--excludeDir` and
`--includeDir`: the former is applied to relative directory entries
and the latter is applied to the whole paths
+ Nimgrep can search multi-line, e.g. to find files containing `import`
and then `strutils` use::
'import(.|\n)*?strutils'

114
doc/nimgrep_cmdline.txt Normal file
View file

@ -0,0 +1,114 @@
Usage:
* To search::
nimgrep [options] PATTERN [(FILE/DIRECTORY)*/-]
* To replace::
nimgrep [options] PATTERN --replace REPLACEMENT (FILE/DIRECTORY)*/-
* To list file names::
nimgrep [options] --filenames [PATTERN] [(FILE/DIRECTORY)*]
Positional arguments, from left to right:
1) PATTERN is either Regex (default) or Peg if `--peg` is specified.
PATTERN and REPLACEMENT should be skipped when `--stdin` is specified.
2) REPLACEMENT supports `$1`, `$#` notations for captured groups in PATTERN.
.. DANGER:: `--replace` mode **DOES NOT** ask confirmation
unless `--confirm` is specified!
3) Final arguments are a list of paths (FILE/DIRECTORY) or a standalone
minus `-` or not specified (empty):
* empty, current directory `.` is assumed (not with `--replace`)
.. Note:: so when no FILE/DIRECTORY/`-` is specified nimgrep
does **not** read the pipe, but searches files in the current
dir instead!
* `-`, read buffer once from stdin: pipe or terminal input;
in `--replace` mode the result is directed to stdout;
it's not compatible with `--stdin`, `--filenames`, or `--confirm`
For any given DIRECTORY nimgrep searches only its immediate files without
traversing sub-directories unless `--recursive` is specified.
In replacement mode we require all 3 positional arguments to avoid damaging.
Options:
* Mode of operation:
--find, -f find the PATTERN (default)
--replace, -! replace the PATTERN to REPLACEMENT, rewriting the files
--confirm confirm each occurrence/replacement; there is a chance
to abort any time without touching the file
--filenames just list filenames. Provide a PATTERN to find it in
the filenames (not in the contents of a file) or run
with empty pattern to just list all files::
nimgrep --filenames # In current dir
nimgrep --filenames "" DIRECTORY
# Note empty pattern "", lists all files in DIRECTORY
* Interprete patterns:
--peg PATTERN and PAT are Peg
--re PATTERN and PAT are regular expressions (default)
--rex, -x use the "extended" syntax for the regular expression
so that whitespace is not significant
--word, -w matches should have word boundaries (buggy for pegs!)
--ignoreCase, -i be case insensitive in PATTERN and PAT
--ignoreStyle, -y be style insensitive in PATTERN and PAT
.. Note:: PATERN and patterns PAT (see below in other options) are all either
Regex or Peg simultaneously and options `--rex`, `--word`, `--ignoreCase`,
and `--ignoreStyle` are applied to all of them.
* File system walk:
--recursive, -r process directories recursively
--follow follow all symlinks when processing recursively
--ext:EX1|EX2|... only search the files with the given extension(s),
empty one ("--ext") means files with missing extension
--noExt:EX1|... exclude files having given extension(s), use empty one to
skip files with no extension (like some binary files are)
--includeFile:PAT search only files whose names contain pattern PAT
--excludeFile:PAT skip files whose names contain pattern PAT
--includeDir:PAT search only files with their whole directory path
containing PAT
--excludeDir:PAT skip directories whose name (not path)
contain pattern PAT
--if,--ef,--id,--ed abbreviations of the 4 options above
--sortTime, -s[:asc|desc]
order files by the last modification time (default: off):
ascending (recent files go last) or descending
* Filter file content:
--match:PAT select files containing a (not displayed) match of PAT
--noMatch:PAT select files not containing any match of PAT
--bin:on|off|only process binary files? (detected by \0 in first 1K bytes)
(default: on - binary and text files treated the same way)
--text, -t process only text files, the same as `--bin:off`
* Represent results:
--nocolor output will be given without any colors
--color[:on] force color even if output is redirected (default: auto)
--colorTheme:THEME select color THEME from `simple` (default),
`bnw` (black and white), `ack`, or `gnu` (GNU grep)
--count only print counts of matches for files that matched
--context:N, -c:N print N lines of leading context before every match and
N lines of trailing context after it (default N: 0)
--afterContext:N, -a:N
print N lines of trailing context after every match
--beforeContext:N, -b:N
print N lines of leading context before every match
--group, -g group matches by file
--newLine, -l display every matching line starting from a new line
--cols[:N] limit max displayed columns/width of output lines from
files by N characters, cropping overflows (default: off)
--cols:auto, -% calculate columns from terminal width for every line
--onlyAscii, -@ display only printable ASCII Latin characters 0x20-0x7E
substitutions: 0 -> ^@, 1 -> ^A, ... 0x1F -> ^_,
0x7F -> '7F, ..., 0xFF -> 'FF
* Miscellaneous:
--threads:N, -j:N speed up search by N additional workers (default: 0, off)
--stdin read PATTERN from stdin (to avoid the shell's confusing
quoting rules) and, if `--replace` given, REPLACEMENT
--verbose be verbose: list every processed file
--help, -h shows this help
--version, -v shows the version

101
tools/nimgrep.nim
View file

@ -16,106 +16,7 @@ const
Version & """ Version & """
(c) 2012-2020 Andreas Rumpf (c) 2012-2020 Andreas Rumpf
""" & slurp "../doc/nimgrep_cmdline.txt"
Usage:
* To search:
nimgrep [options] PATTERN [(FILE/DIRECTORY)*/-]
* To replace:
nimgrep [options] PATTERN --replace REPLACEMENT (FILE/DIRECTORY)*/-
* To list file names:
nimgrep [options] --filenames [PATTERN] [(FILE/DIRECTORY)*]
Positional arguments, from left to right:
* PATERN is either Regex (default) or Peg if --peg is specified.
PATTERN and REPLACEMENT should be skipped when --stdin is specified.
* REPLACEMENT supports $1, $# notations for captured groups in PATTERN.
Note: --replace mode DOES NOT ask confirmation unless --confirm is specified!
* Final arguments are a list of paths (FILE/DIRECTORY) or a standalone
minus '-' (pipe) or not specified (empty). Note for the empty case: when
no FILE/DIRECTORY/- is specified nimgrep DOES NOT read the pipe, but
searches files in the current dir instead!
- read buffer once from stdin: pipe or terminal input;
in --replace mode the result is directed to stdout;
it's not compatible with --stdin, --filenames, --confirm
(empty) current directory '.' is assumed (not with --replace)
For any given DIRECTORY nimgrep searches only its immediate files without
traversing sub-directories unless --recursive is specified.
In replacement mode all 3 positional arguments are required to avoid damaging.
Options:
* Mode of operation:
--find, -f find the PATTERN (default)
--replace, -! replace the PATTERN to REPLACEMENT, rewriting the files
--confirm confirm each occurrence/replacement; there is a chance
to abort any time without touching the file
--filenames just list filenames. Provide a PATTERN to find it in
the filenames (not in the contents of a file) or run
with empty pattern to just list all files:
nimgrep --filenames # In current directory
nimgrep --filenames "" DIRECTORY # Note empty pattern ""
* Interprete patterns:
--peg PATTERN and PAT are Peg
--re PATTERN and PAT are regular expressions (default)
--rex, -x use the "extended" syntax for the regular expression
so that whitespace is not significant
--word, -w matches should have word boundaries (buggy for pegs!)
--ignoreCase, -i be case insensitive in PATTERN and PAT
--ignoreStyle, -y be style insensitive in PATTERN and PAT
NOTE: PATERN and patterns PAT (see below in other options) are all either
Regex or Peg simultaneously and options --rex, --word, --ignoreCase,
--ignoreStyle are applied to all of them.
* File system walk:
--recursive, -r process directories recursively
--follow follow all symlinks when processing recursively
--ext:EX1|EX2|... only search the files with the given extension(s),
empty one ("--ext") means files with missing extension
--noExt:EX1|... exclude files having given extension(s), use empty one to
skip files with no extension (like some binary files are)
--includeFile:PAT search only files whose names contain pattern PAT
--excludeFile:PAT skip files whose names contain pattern PAT
--includeDir:PAT search only files with whole directory path containing PAT
--excludeDir:PAT skip directories whose name (not path) contain pattern PAT
--if,--ef,--id,--ed abbreviations of 4 options above
--sortTime order files by the last modification time (default: off):
-s[:asc|desc] ascending (recent files go last) or descending
* Filter file content:
--match:PAT select files containing a (not displayed) match of PAT
--noMatch:PAT select files not containing any match of PAT
--bin:on|off|only process binary files? (detected by \0 in first 1K bytes)
(default: on - binary and text files treated the same way)
--text, -t process only text files, the same as --bin:off
* Represent results:
--nocolor output will be given without any colors
--color[:on] force color even if output is redirected (default: auto)
--colorTheme:THEME select color THEME from 'simple' (default),
'bnw' (black and white) ,'ack', or 'gnu' (GNU grep)
--count only print counts of matches for files that matched
--context:N, -c:N print N lines of leading context before every match and
N lines of trailing context after it (default N: 0)
--afterContext:N,
-a:N print N lines of trailing context after every match
--beforeContext:N,
-b:N print N lines of leading context before every match
--group, -g group matches by file
--newLine, -l display every matching line starting from a new line
--cols[:N] limit max displayed columns/width of output lines from
files by N characters, cropping overflows (default: off)
--cols:auto, -% calculate columns from terminal width for every line
--onlyAscii, -@ display only printable ASCII Latin characters 0x20-0x7E
substitutions: 0 -> ^@, 1 -> ^A, ... 0x1F -> ^_,
0x7F -> '7F, ..., 0xFF -> 'FF
* Miscellaneous:
--threads:N, -j:N speed up search by N additional workers (default: 0, off)
--stdin read PATTERN from stdin (to avoid the shell's confusing
quoting rules) and, if --replace given, REPLACEMENT
--verbose be verbose: list every processed file
--help, -h shows this help
--version, -v shows the version
"""
# Limitations / ideas / TODO: # Limitations / ideas / TODO:
# * No unicode support with --cols # * No unicode support with --cols