mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2025-12-29 09:24:36 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
0641df33aabe25d0c83b00a334cc157a8ca50607
Nim/doc/nimgrep.md
Andrey Makarov 417b90a7e5 Improve Markdown code blocks & start moving docs to Markdown style (#19954) 
- add additional parameters parsing (other implementations will just
  ignore them). E.g. if in RST we have:

  .. code:: nim
     :test: "nim c $1"

     ...

  then in Markdown that will be:

  ```nim test="nim c $1"
  ...
  ```

- implement Markdown interpretation of additional indentation which is
  less than 4 spaces (>=4 spaces is a code block but it's not
implemented yet). RST interpretes it as quoted block, for Markdown it's
just normal paragraphs.
- add separate `md2html` and `md2tex` commands. This is to separate
  Markdown behavior in cases when it diverges w.r.t. RST significantly —
most conspicously like in the case of additional indentation above, and
also currently the contradicting inline rule of Markdown is also turned
on only in `md2html` and `md2tex`. **Rationale:** mixing Markdown and
RST arbitrarily is a way to nowhere, we need to provide a way to fix the
particular behavior. Note that still all commands have **both** Markdown
and RST features **enabled**. In this PR `*.nim` files can be processed
only in Markdown mode, while `md2html` is for `*.md` files and
`rst2html` for `*.rst` files.
- rename `*.rst` files to `.*md` as our current default behavior is
  already Markdown-ish
- convert code blocks in `docgen.rst` to Markdown style as an example.
  Other code blocks will be converted in the follow-up PRs
- fix indentation inside Markdown code blocks — additional indentation
  is preserved there
- allow more than 3 backticks open/close blocks (tildas \~ are still not
  allowed to avoid conflict with RST adornment headings) see also
https://github.com/nim-lang/RFCs/issues/355
- better error messages
- (other) fix a bug that admonitions cannot be used in sandbox mode; fix
  annoying warning on line 2711
2022-07-15 19:27:54 +02:00

1.9 KiB
Raw Blame History

========================= nimgrep User's manual

:Author: Andreas Rumpf :Version: 1.6.0

.. default-role:: option .. contents::

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 confirmation for every single replace operation can be requested.

Nimgrep has particularly good support for Nim's eccentric style insensitivity (see option -y below). Apart from that it is a generic text manipulation tool.

Installation

Compile nimgrep with the command:

.. code:: cmd nim c -d:release tools/nimgrep.nim

And copy the executable somewhere in your $PATH.

Command line switches

.. include:: nimgrep_cmdline.txt

Examples

All examples below use default PCRE Regex patterns:

  • To search recursively in Nim files using style-insensitive identifiers:

    .. code:: cmd nimgrep --recursive --ext:'nim|nims' --ignoreStyle

    short: -r --ext:'nim|nims' -y

    .. Note:: we used ' quotes to avoid special treatment of | symbol for shells like Bash

  • To exclude version control directories (Git, Mercurial=hg, Subversion=svn) from the search:

    .. code:: cmd nimgrep --excludeDir:'^.git$' --excludeDir:'^.hg$' --excludeDir:'^.svn$'

    short: --ed:'^.git$' --ed:'^.hg$' --ed:'^.svn$'

  • To search only in paths containing the tests sub-directory recursively:

    .. code:: cmd nimgrep --recursive --includeDir:'(^|/)tests($|/)'

    short: -r --id:'(^|/)tests($|/)'

    .. Attention:: note the subtle difference between --excludeDir:option: and --includeDir:option:: 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 pattern 'import(.|\n)*?strutils':option:.