autoload/explainpat.vim

   1 " File:         explainpat.vim
   2 " Created:      2011 Nov 02
   3 " Last Change:  2012 Dec 19
   4 " Rev Days:     3
   5 " Author:       Andy Wokula <anwoku@yahoo.de>
   6 " License:      Vim License, see :h license
   7 " Version:      0.2
   8
   9 " Implements :ExplainPattern [pattern]
  10
  11 " TODO {{{
  12 " - more testing, completeness check
  13 " - detailed collections
  14 " - \z
  15 " ? literal string: also print the unescaped magic items
  16 " ? literal string: show leading/trailing spaces
  17 " + start of "first" capturing group, start of 2nd ...
  18 " + `\|' should get less indent than the branches, do we need to create an
  19 "   AST?        ! no, keep it straight forward
  20 " + \%[...]
  21 " + \{, \{-
  22 "}}}
  23
  24 " Init Folklore {{{
  25 let s:cpo_save = &cpo
  26 set cpo&vim
  27 let g:explainpat#loaded = 1
  28 "}}}
  29
  30 func! explainpat#ExplainPattern(cmd_arg) "{{{
  31     if a:cmd_arg == ""
  32         " let pattern_str = nwo#vis#Get()
  33         echo "(usage) :ExplainPattern [{register} | {pattern}]"
  34         return
  35     elseif strlen(a:cmd_arg) == 1 && a:cmd_arg =~ '["@0-9a-z\-:.*+/]'
  36         echo 'Register:' a:cmd_arg
  37         let pattern_str = getreg(a:cmd_arg)
  38     else
  39         let pattern_str = a:cmd_arg
  40     endif
  41
  42     echo printf('Pattern: %s', pattern_str)
  43     let magicpat = nwo#magic#MakeMagic(pattern_str)
  44     if magicpat !=# pattern_str
  45         echo printf('Magic Pattern: %s', magicpat)
  46     endif
  47
  48     " hmm, we need state for \%[ ... ]
  49     let s:in_opt_atoms = 0
  50     let s:capture_group_nr = 0
  51
  52     let hulit = s:NewHelpPrinter()
  53     call hulit.AddIndent('  ')
  54     let bull = s:NewTokenBiter(magicpat, '')
  55     while !bull.AtEnd()
  56         let item = bull.Bite(s:magic_item_pattern)
  57         if item != ''
  58             let Doc = get(s:doc, item, '')
  59             if empty(Doc)
  60                 call hulit.AddLiteral(item)
  61             elseif type(Doc) == s:STRING
  62                 call hulit.Print(item, Doc)
  63             elseif type(Doc) == s:FUNCREF
  64                 call call(Doc, [bull, hulit, item])
  65             endif
  66         else
  67             echoerr printf('ExplainPattern: cannot parse "%s"', bull.Rest())
  68             break
  69         endif
  70         unlet Doc
  71     endwhile
  72     call hulit.FlushLiterals()
  73 endfunc "}}}
  74
  75 " s: types {{{
  76 let s:STRING = type("")
  77 let s:DICT   = type({})
  78 let s:FUNCREF = type(function("tr"))
  79 " }}}
  80
  81 let s:magic_item_pattern = '\C^\%(\\\%(@<.\|%[dxouU[(^$V#<>]\=\|z[1-9se(]\|{\|@[>=!]\|_[[^$.]\=\|.\)\|.\)'
  82
  83 let s:doc = {} " {{{
  84 " this is all the help data ...
  85 "   strings, funcrefs and intermixed s:DocFoo() functions
  86 " strongly depends on s:magic_item_pattern
  87
  88 func! s:DocOrBranch(bull, hulit, item) "{{{
  89     call a:hulit.RemIndent()
  90     call a:hulit.Print(a:item, "OR branch")
  91     call a:hulit.AddIndent('  ')
  92 endfunc "}}}
  93
  94 let s:doc['\|'] = function("s:DocOrBranch")
  95 let s:doc['\&'] = "AND branch"
  96
  97 let s:ord = split('n first second third fourth fifth sixth seventh eighth ninth')
  98
  99 func! s:DocGroupStart(bull, hulit, item) "{{{
 100     if a:item == '\%('
 101         call a:hulit.Print(a:item, "start of non-capturing group")
 102     else " a:item == '\('
 103         let s:capture_group_nr += 1
 104         call a:hulit.Print(a:item, printf("start of %s capturing group", get(s:ord, s:capture_group_nr, '(invalid)')))
 105     endif
 106     call a:hulit.AddIndent('| ', '  ')
 107 endfunc "}}}
 108 func! s:DocGroupEnd(bull, hulit, item) "{{{
 109     call a:hulit.RemIndent(2)
 110     call a:hulit.Print(a:item, "end of group")
 111 endfunc "}}}
 112
 113 let s:doc['\('] = function("s:DocGroupStart")
 114 let s:doc['\%('] = function("s:DocGroupStart")
 115 let s:doc['\)'] =  function("s:DocGroupEnd")
 116
 117 let s:doc['\z('] = "only in syntax scripts"
 118 let s:doc['*'] = "(multi) zero or more of the preceding atom"
 119 let s:doc['\+'] = "(multi) one or more of the preceding atom"
 120 let s:doc['\='] = "(multi) zero or one of the preceding atom"
 121 let s:doc['\?'] = "(multi) zero or one of the preceding atom"
 122 " let s:doc['\{'] = "(multi) N to M, greedy"
 123 " let s:doc['\{-'] = "(multi) N to M, non-greedy"
 124
 125 func! s:DocBraceMulti(bull, hulit, item) "{{{
 126     let rest = a:bull.Bite('^-\=\d*\%(,\d*\)\=}')
 127     if rest != ""
 128         if rest == '-}'
 129             call a:hulit.Print(a:item. rest, "non-greedy version of `*'")
 130         elseif rest =~ '^-'
 131             call a:hulit.Print(a:item. rest, "(multi) N to M, non-greedy")
 132         else
 133             call a:hulit.Print(a:item. rest, "(multi) N to M, greedy")
 134         endif
 135     else
 136         echoerr printf('ExplainPattern: cannot parse %s', a:item. a:bull.Rest())
 137     endif
 138 endfunc "}}}
 139
 140 let s:doc['\{'] = function("s:DocBraceMulti")
 141
 142 let s:doc['\@>'] = "(multi) match preceding atom like a full pattern"
 143 let s:doc['\@='] = "(assertion) require match for preceding atom"
 144 let s:doc['\@!'] = "(assertion) forbid match for preceding atom"
 145 let s:doc['\@<='] = "(assertion) require match for preceding atom to the left"
 146 let s:doc['\@<!'] = "(assertion) forbid match for preceding atom to the left"
 147 let s:doc['^'] = "(assertion) require match at start of line"
 148 let s:doc['\_^'] = "(assertion) like `^', allowed anywhere in the pattern"
 149 let s:doc['$'] = "(assertion) require match at end of line"
 150 let s:doc['\_$'] = "(assertion) like `$', allowed anywhere in the pattern"
 151 let s:doc['.'] = "match any character"
 152 let s:doc['\_.'] = "match any character or newline"
 153
 154 func! s:DocUnderscore(bull, hulit, item) "{{{
 155     let cclass = a:bull.Bite('^\a')
 156     if cclass != ''
 157         let cclass_doc = get(s:doc, '\'. cclass, '(invalid character class)')
 158         call a:hulit.Print(a:item. cclass, printf('%s or end-of-line', cclass_doc))
 159     else
 160         echoerr printf('ExplainPattern: cannot parse %s', a:item. matchstr(a:bull.Rest(), '.'))
 161     endif
 162 endfunc "}}}
 163
 164 let s:doc['\_'] = function("s:DocUnderscore")
 165 let s:doc['\<'] = "(assertion) require match at begin of word, :h word"
 166 let s:doc['\>'] = "(assertion) require match at end of word, :h word"
 167 let s:doc['\zs'] = "set begin of match here"
 168 let s:doc['\ze'] = "set end of match here"
 169 let s:doc['\%^'] = "(assertion) match at begin of buffer"
 170 let s:doc['\%$'] = "(assertion) match at end of buffer"
 171 let s:doc['\%V'] = "(assertion) match within the Visual area"
 172 let s:doc['\%#'] = "(assertion) match with cursor position"
 173
 174 " \%'m   \%<'m   \%>'m
 175 " \%23l  \%<23l  \%>23l
 176 " \%23c  \%<23c  \%>23c
 177 " \%23v  \%<23v  \%>23v
 178 " backslash percent at/before/after
 179 func! s:DocBspercAt(bull, hulit, item) "{{{
 180     let rest = a:bull.Bite('^\%(''.\|\d\+[lvc]\)\C')
 181     if rest[0] == "'"
 182         call a:hulit.Print(a:item.rest, "(assertion) match with position of mark ". rest[1])
 183     else
 184         let number = rest[:-2]
 185         let type = rest[-1:]
 186         if type ==# "l"
 187             call a:hulit.Print(a:item.rest, "match in line ". number)
 188         elseif type ==# "c"
 189             call a:hulit.Print(a:item.rest, "match in column ". number)
 190         elseif type ==# "v"
 191             call a:hulit.Print(a:item.rest, "match in virtual column ". number)
 192         else
 193             echoerr printf('ExplainPattern: incomplete item %s', a:item. rest)
 194         endif
 195     endif
 196 endfunc "}}}
 197 func! s:DocBspercBefore(bull, hulit, item) "{{{
 198     let rest = a:bull.Bite('^\%(''.\|\d\+[lvc]\)\C')
 199     if rest[0] == "'"
 200         call a:hulit.Print(a:item.rest, "(assertion) match before position of mark ". rest[1])
 201     else
 202         let number = rest[:-2]
 203         let type = rest[-1:]
 204         if type ==# "l"
 205             call a:hulit.Print(a:item.rest, printf("match above line %d (towards start of buffer)", number))
 206         elseif type ==# "c"
 207             call a:hulit.Print(a:item.rest, "match before column ". number)
 208         elseif type ==# "v"
 209             call a:hulit.Print(a:item.rest, "match before virtual column ". number)
 210         else
 211             echoerr printf('ExplainPattern: incomplete item %s', a:item. rest)
 212         endif
 213     endif
 214 endfunc "}}}
 215 func! s:DocBspercAfter(bull, hulit, item) "{{{
 216     let rest = a:bull.Bite('^\%(''.\|\d\+[lvc]\)\C')
 217     if rest[0] == "'"
 218         call a:hulit.Print(a:item.rest, "(assertion) match after position of mark ". rest[1])
 219     else
 220         let number = rest[:-2]
 221         let type = rest[-1:]
 222         if type ==# "l"
 223             call a:hulit.Print(a:item.rest, printf("match below line %d (towards end of buffer)", number))
 224         elseif type ==# "c"
 225             call a:hulit.Print(a:item.rest, "match after column ". number)
 226         elseif type ==# "v"
 227             call a:hulit.Print(a:item.rest, "match after virtual column ". number)
 228         else
 229             echoerr printf('ExplainPattern: incomplete item %s', a:item. rest)
 230         endif
 231     endif
 232 endfunc "}}}
 233
 234 let s:doc['\%'] = function("s:DocBspercAt")
 235 let s:doc['\%<'] = function("s:DocBspercBefore")
 236 let s:doc['\%>'] = function("s:DocBspercAfter")
 237
 238 let s:doc['\i'] = "identifier character (see 'isident' option)"
 239 let s:doc['\I'] = "like \"\\i\", but excluding digits"
 240 let s:doc['\k'] = "keyword character (see 'iskeyword' option)"
 241 let s:doc['\K'] = "like \"\\k\", but excluding digits"
 242 let s:doc['\f'] = "file name character (see 'isfname' option)"
 243 let s:doc['\F'] = "like \"\\f\", but excluding digits"
 244 let s:doc['\p'] = "printable character (see 'isprint' option)"
 245 let s:doc['\P'] = "like \"\\p\", but excluding digits"
 246 let s:doc['\s'] = "whitespace character: <Space> and <Tab>"
 247 let s:doc['\S'] = "non-whitespace character; opposite of \\s"
 248 let s:doc['\d'] = "digit: [0-9]"
 249 let s:doc['\D'] = "non-digit: [^0-9]"
 250 let s:doc['\x'] = "hex digit: [0-9A-Fa-f]"
 251 let s:doc['\X'] = "non-hex digit: [^0-9A-Fa-f]"
 252 let s:doc['\o'] = "octal digit: [0-7]"
 253 let s:doc['\O'] = "non-octal digit: [^0-7]"
 254 let s:doc['\w'] = "word character: [0-9A-Za-z_]"
 255 let s:doc['\W'] = "non-word character: [^0-9A-Za-z_]"
 256 let s:doc['\h'] = "head of word character: [A-Za-z_]"
 257 let s:doc['\H'] = "non-head of word character: [^A-Za-z_]"
 258 let s:doc['\a'] = "alphabetic character: [A-Za-z]"
 259 let s:doc['\A'] = "non-alphabetic character: [^A-Za-z]"
 260 let s:doc['\l'] = "lowercase character: [a-z]"
 261 let s:doc['\L'] = "non-lowercase character: [^a-z]"
 262 let s:doc['\u'] = "uppercase character: [A-Z]"
 263 let s:doc['\U'] = "non-uppercase character: [^A-Z]"
 264
 265 let s:doc['\e'] = "match <Esc>"
 266 let s:doc['\t'] = "match <Tab>"
 267 let s:doc['\r'] = "match <CR>"
 268 let s:doc['\b'] = "match CTRL-H"
 269 let s:doc['\n'] = "match a newline"
 270 let s:doc['~'] = "match the last given substitute string"
 271 let s:doc['\1'] = "match first captured string"
 272 let s:doc['\2'] = "match second captured string"
 273 let s:doc['\3'] = "match third captured string"
 274 let s:doc['\4'] = "match fourth captured string "
 275 let s:doc['\5'] = "match fifth captured string"
 276 let s:doc['\6'] = "match sixth captured string"
 277 let s:doc['\7'] = "match seventh captured string"
 278 let s:doc['\8'] = "match eighth captured string"
 279 let s:doc['\9'] = "match ninth captured string"
 280
 281 " \z1
 282 " \z2
 283 " \z9
 284
 285 " from MakeMagic()
 286 " skip the rest of a collection
 287 let s:coll_skip_pat = '^\^\=]\=\%(\%(\\[\^\]\-\\bertn]\|\[:\w\+:]\|[^\]]\)\@>\)*]'
 288
 289 func! s:DocCollection(bull, hulit, item) "{{{
 290     let collstr = a:bull.Bite(s:coll_skip_pat)
 291     let inverse = collstr =~ '^\^'
 292     let with_nl = a:item == '\_['
 293     let descr = inverse ? printf('collection not matching [%s', collstr[1:]) : 'collection'
 294     let descr_nl = printf("%s%s", (inverse && with_nl ? ', but' : ''), (with_nl ? ' with end-of-line added' : ''))
 295     call a:hulit.Print(a:item. collstr, descr. descr_nl)
 296 endfunc "}}}
 297
 298 let s:doc['['] = function("s:DocCollection")
 299 let s:doc['\_['] = function("s:DocCollection")
 300
 301 func! s:DocOptAtoms(bull, hulit, item) "{{{
 302     if a:item == '\%['
 303         call a:hulit.Print(a:item, "start a sequence of optionally matched atoms")
 304         let s:in_opt_atoms = 1
 305         call a:hulit.AddIndent('. ')
 306     else " a:item == ']'
 307         if s:in_opt_atoms
 308             call a:hulit.RemIndent()
 309             call a:hulit.Print(a:item, "end of optionally matched atoms")
 310             let s:in_opt_atoms = 0
 311         else
 312             call a:hulit.AddLiteral(a:item)
 313         endif
 314     endif
 315 endfunc "}}}
 316
 317 " let s:doc['\%['] = "start a sequence of optionally matched atoms"
 318 let s:doc['\%['] = function("s:DocOptAtoms")
 319 let s:doc[']'] = function("s:DocOptAtoms")
 320
 321 let s:doc['\c'] = "ignore case while matching the pattern"
 322 let s:doc['\C'] = "match case while matching the pattern"
 323 let s:doc['\Z'] = "ignore composing characters in the pattern"
 324
 325 " \%d 123
 326 " \%x 2a
 327 " \%o 0377
 328 " \%u 20AC
 329 " \%U 1234abcd
 330
 331 func! s:DocBspercDecimal(bull, hulit, item) "{{{
 332     let number = a:bull.Bite('^\d\{,3}')
 333     let char = strtrans(nr2char(str2nr(number)))
 334     call a:hulit.Print(a:item. number, printf("match character specified by decimal number %s (%s)", number, char))
 335 endfunc "}}}
 336 func! s:DocBspercHexTwo(bull, hulit, item) "{{{
 337     let number = a:bull.Bite('^\x\{,2}')
 338     let char = strtrans(nr2char(str2nr(number,16)))
 339     call a:hulit.Print(a:item. number, printf("match character specified with hex number 0x%s (%s)", number, char))
 340 endfunc "}}}
 341 func! s:DocBspercOctal(bull, hulit, item) "{{{
 342     let number = a:bull.Bite('^\o\{,4}')
 343     let char = strtrans(nr2char(str2nr(number,8)))
 344     call a:hulit.Print(a:item. number, printf("match character specified with octal number 0%s (%s)", substitute(number, '^0*', '', ''), char))
 345 endfunc "}}}
 346 func! s:DocBspercHexFour(bull, hulit, item) "{{{
 347     let number = a:bull.Bite('^\x\{,4}')
 348     let char = has("multi_byte_encoding") ? ' ('. strtrans(nr2char(str2nr(number,16))).')' : ''
 349     call a:hulit.Print(a:item. number, printf("match character specified with hex number 0x%s%s", number, char))
 350 endfunc "}}}
 351 func! s:DocBspercHexEight(bull, hulit, item) "{{{
 352     let number = a:bull.Bite('^\x\{,8}')
 353     let char = has("multi_byte_encoding") ? ' ('. strtrans(nr2char(str2nr(number,16))).')' : ''
 354     call a:hulit.Print(a:item. number, printf("match character specified with hex number 0x%s%s", number, char))
 355 endfunc "}}}
 356
 357 let s:doc['\%d'] = function("s:DocBspercDecimal") " 123
 358 let s:doc['\%x'] = function("s:DocBspercHexTwo") " 2a
 359 let s:doc['\%o'] = function("s:DocBspercOctal") " 0377
 360 let s:doc['\%u'] = function("s:DocBspercHexFour") " 20AC
 361 let s:doc['\%U'] = function("s:DocBspercHexEight") " 1234abcd
 362
 363 " \m
 364 " \M
 365 " \v
 366 " \V
 367 "}}}
 368
 369 func! s:NewHelpPrinter() "{{{
 370     let obj = {}
 371     let obj.literals = ''
 372     let obj.indents = []
 373     let obj.len = 0         " can be negative (!)
 374
 375     func! obj.Print(str, ...) "{{{
 376         call self.FlushLiterals()
 377         let indstr = join(self.indents, '')
 378         echohl Comment
 379         echo indstr
 380         echohl None
 381         if a:0 == 0
 382             echon a:str
 383         else
 384             " echo indstr. printf("`%s'   %s", a:str, a:1)
 385             echohl PreProc
 386             echon printf("%-10s", a:str)
 387             echohl None
 388             echohl Comment
 389             echon printf(" %s", a:1)
 390             echohl None
 391         endif
 392     endfunc "}}}
 393
 394     func! obj.AddLiteral(item) "{{{
 395         let self.literals .= a:item
 396     endfunc "}}}
 397
 398     func! obj.FlushLiterals() "{{{
 399         if self.literals == ''
 400             return
 401         endif
 402         let indstr = join(self.indents, '')
 403         echohl Comment
 404         echo indstr
 405         echohl None
 406         if self.literals =~ '^\s\|\s$'
 407             echon printf("%-10s", '"'. self.literals. '"')
 408         else
 409             echon printf("%-10s", self.literals)
 410         endif
 411         echohl Comment
 412         echon " literal string"
 413         if exists("*strchars")
 414             if self.literals =~ '\\'
 415                 let self.literals = substitute(self.literals, '\\\(.\)', '\1', 'g')
 416             endif
 417             let so = self.literals =~ '[^ ]' ? '' : ', spaces only'
 418             echon " (". strchars(self.literals). " atom(s)". so.")"
 419         endif
 420         echohl None
 421         let self.literals = ''
 422     endfunc  "}}}
 423
 424     func! obj.AddIndent(...) "{{{
 425         call self.FlushLiterals()
 426         if self.len >= 0
 427             call extend(self.indents, copy(a:000))
 428         elseif self.len + a:0 >= 1
 429             call extend(self.indents, a:000[-(self.len+a:0):])
 430         endif
 431         let self.len += a:0
 432     endfunc "}}}
 433
 434     func! obj.RemIndent(...) "{{{
 435         call self.FlushLiterals()
 436         if a:0 == 0
 437             if self.len >= 1
 438                 call remove(self.indents, -1)
 439             endif
 440             let self.len -= 1
 441         else
 442             if self.len > a:1
 443                 call remove(self.indents, -a:1, -1)
 444             elseif self.len >= 1
 445                 call remove(self.indents, 0, -1)
 446             endif
 447             let self.len -= a:1
 448         endif
 449     endfunc "}}}
 450
 451     return obj
 452 endfunc "}}}
 453
 454 func! s:NewTokenBiter(str, ...) "{{{
 455     " {str}     string to eat pieces from
 456     " {a:1}     pattern to skip separators
 457     let whitepat = a:0>=1 ? a:1 : '^\s*'
 458     let obj = {'str': a:str, 'whitepat': whitepat}
 459
 460     " consume piece from start of input matching {pat}
 461     func! obj.Bite(pat) "{{{
 462         " {pat}     should start with '^'
 463         let skip = matchend(self.str, self.whitepat)
 464         let bite = matchstr(self.str, a:pat, skip)
 465         let self.str = strpart(self.str, matchend(self.str, self.whitepat, skip + strlen(bite)))
 466         return bite
 467     endfunc "}}}
 468
 469     " get the unparsed rest of input
 470     func! obj.Rest() "{{{
 471         return self.str
 472     endfunc "}}}
 473
 474     " check if end of input reached
 475     func! obj.AtEnd() "{{{
 476         return self.str == ""
 477     endfunc "}}}
 478
 479     return obj
 480 endfunc "}}}
 481
 482 " Modeline: {{{1
 483 let &cpo = s:cpo_save
 484 unlet s:cpo_save
 485 " vim:ts=8:fdm=marker: