*explainpat.txt*    Give detailed help on a regexp pattern.

		    For Vim version 7.0.  Last change: 2017 Oct 20
		    By Andy Wokula <anwoku@yahoo.de>

						*explainpat* *explainpat.vim*
ExplainPat is a plugin to inspect a Vim regexp pattern and show a line of help
for each found regexp item.  Purpose is to get a better view on somebody
else's complex regexp string.  It may also help with spotting mistakes.

If you find that it explains something wrong, please drop me an email.

URL http://vim.sourceforge.net/scripts/script.php?script_id=4364
==============================================================================
						*:ExplainPattern*
:ExplainPattern {pattern}
:ExplainPattern {register}
			inspect the given Vim {pattern} and print a line of
			help (with color) for each found pattern item.  Nested
			items get extra indent.

			A single-char argument is used as {register} argument:
				/	explain the last search pattern
				*	explain pattern from the clipboard
				a	explain pattern from register a
				etc.

Notes:
The pattern is first converted into a purely |magic| pattern using
|nwo#magic#MakeMagic()|.  This means that embedded |/\V| |/\M| |/\m| |/\v|
specifiers are effectively removed from the explanation.

:ExplainPattern also accepts some invalid patterns: >
	:ExplainPattern \)
	Pattern: \)
	\)         end of group

==============================================================================
TODO:

Ideas:
- If the user already knows regular expressions but of a different kind,
  explain items in that different language.
  Other regexp idioms:
	Perl, Python, Emacs, Java, C#, Sed, Grep;
	Vim ... very magic, nomagic, very nomagic
  Possible config var name:
  	g:explainpat_user_knows = "Perl"
  	g:explainpat_background = "Perl"
	g:explainpat_in_terms_of = "Perl"
	g:explainpat_language = "Perl"

==============================================================================
History:

v0.7
+ BF `\{3,4\}` not accepted, only `\{3,4}`

v0.6
+ BF `[]` is a literal string (not a collection)

v0.5
+ BF `$\n^`
+ wording: `\|` is not an "OR branch" (it separates or branches)
+ NF added tests (not part of release)
+ NF accept custom help printer (for testing purpose, could also be used to
  export HTML etc.)

v0.4
+ BF `[foo` is a literal string
+ BF for |/star|, |/^| and |/$|, distinguish position in the pattern
  (sometimes these become literal); special cases: `^**`, `^^`, `\c^^`, `$$`,
  `a\|^b`, `a\&*b`, `[ab`, `\_[ab`, ...

v0.3
+ BF accept `\z(...\)` and `\z[N]`
+ BF accept `[=a=]` and `[.a.]` in collections

v0.2
+ include vim_use suggestions [2012 Dec 19]
  * for collections [^...], add "not matching [...]"
  * fix `\%>'a1`
  * more detailed `\%x31`

v0.1 (initial version)
+ start of "first" capturing group, start of 2nd ...
+ `\|` should get less indent than the branches, do we need to create an
  AST?	! no, keep it straight forward
+ `\%[...]`
+ `\{`, `\{-`

==============================================================================
vim:tw=78:fo=tcq2:sts=0:ts=8:sw=8:fdm=marker:fmr=^_\^,^\^:ft=help: