.vim/bundle/explainpat/doc/explainpat.txt

   1 *explainpat.txt*    Give detailed help on a regexp pattern.
   2
   3                     For Vim version 7.0.  Last change: 2017 Dec 15
   4                     By Andy Wokula <anwoku@yahoo.de>
   5
   6                                                 *explainpat* *explainpat.vim*
   7 ExplainPat is a plugin to inspect a Vim regexp pattern and show a line of help
   8 for each found regexp item.  Purpose is to get a better view on somebody
   9 else's complex regexp string.  It may also help with spotting mistakes.
  10
  11 If you find that it explains something wrong, please drop me an email.
  12
  13 URL http://vim.sourceforge.net/scripts/script.php?script_id=4364
  14 ==============================================================================
  15                                                 *:ExplainPattern*
  16 :ExplainPattern {pattern}
  17 :ExplainPattern {register}
  18                         inspect the given Vim {pattern} and print a line of
  19                         help (with color) for each found pattern item.  Nested
  20                         items get extra indent.
  21
  22                         A single-char argument is used as {register} argument:
  23                                 /       explain the last search pattern
  24                                 *       explain pattern from the clipboard
  25                                 a       explain pattern from register a
  26                                 etc.
  27
  28 >
  29         :ExplainPattern \C^\%(\\\%(@<\|%#=\|%[dxouU[(^$V#<>]\=\|z[1-9se(]\|@[>=!]\|_[[^$.]\=\|.\)\|.\)
  30
  31 Notes:
  32 The pattern is first converted into a purely |magic| pattern using
  33 |nwo#magic#MakeMagic()|.  This means that embedded |/\V| |/\M| |/\m| |/\v|
  34 specifiers are effectively removed from the explanation.
  35
  36 :ExplainPattern also accepts some invalid patterns: >
  37         :ExplainPattern \)
  38         Pattern: \)
  39         \)         end of group
  40
  41 ==============================================================================
  42 TODO:
  43 ? `\%[...]` can be nested?  But documentation |/\%[]| says no.
  44
  45 Ideas:
  46 - If the user already knows regular expressions but of a different kind,
  47   explain items in that different language.
  48   Other regexp idioms:
  49         Perl, Python, Emacs, Java, C#, Sed, Grep;
  50         Vim ... very magic, nomagic, very nomagic
  51   Possible config var name:
  52         g:explainpat_user_knows = "Perl"
  53         g:explainpat_background = "Perl"
  54         g:explainpat_in_terms_of = "Perl"
  55         g:explainpat_language = "Perl"
  56
  57 ==============================================================================
  58 History:
  59
  60 v0.9
  61 + BF accept `\@123<=` and `\@123<!`
  62
  63 v0.8
  64 * s:NewHelpPrinter() => explainpat#NewHelpPrinter()
  65
  66 v0.7
  67 + BF `\{3,4\}` not accepted, only `\{3,4}`
  68
  69 v0.6
  70 + BF `[]` is a literal string (not a collection)
  71
  72 v0.5
  73 + BF `$\n^`
  74 + wording: `\|` is not an "OR branch" (it separates or branches)
  75 + NF added tests (not part of release)
  76 + NF accept custom help printer (for testing purpose, could also be used to
  77   export HTML etc.)
  78
  79 v0.4
  80 + BF `[foo` is a literal string
  81 + BF for |/star|, |/^| and |/$|, distinguish position in the pattern
  82   (sometimes these become literal); special cases: `^**`, `^^`, `\c^^`, `$$`,
  83   `a\|^b`, `a\&*b`, `[ab`, `\_[ab`, ...
  84
  85 v0.3
  86 + BF accept `\z(...\)` and `\z[N]`
  87 + BF accept `[=a=]` and `[.a.]` in collections
  88
  89 v0.2
  90 + include vim_use suggestions [2012 Dec 19]
  91   * for collections [^...], add "not matching [...]"
  92   * fix `\%>'a1`
  93   * more detailed `\%x31`
  94
  95 v0.1 (initial version)
  96 + start of "first" capturing group, start of 2nd ...
  97 + `\|` should get less indent than the branches, do we need to create an
  98   AST?  ! no, keep it straight forward
  99 + `\%[...]`
 100 + `\{`, `\{-`
 101
 102 ==============================================================================
 103 vim:tw=78:fo=tcq2:sts=0:ts=8:sw=8:fdm=marker:fmr=^_\^,^\^:ft=help: