lib/lyx2lyx/parser_tools.py

   1 # This file is part of lyx2lyx
   2 # -*- coding: utf-8 -*-
   3 # Copyright (C) 2002-2011 Dekel Tsur <dekel@lyx.org>,
   4 # José Matos <jamatos@lyx.org>, Richard Heck <rgheck@comcast.net>
   5 #
   6 # This program is free software; you can redistribute it and/or
   7 # modify it under the terms of the GNU General Public License
   8 # as published by the Free Software Foundation; either version 2
   9 # of the License, or (at your option) any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program; if not, write to the Free Software
  18 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  19
  20
  21 '''
  22 This modules offer several free functions to help parse lines.
  23 More documentaton is below, but here is a quick guide to what
  24 they do. Optional arguments are marked by brackets.
  25
  26 find_token(lines, token, start[, end[, ignorews]]):
  27   Returns the first line i, start <= i < end, on which
  28   token is found at the beginning. Returns -1 if not
  29   found.
  30   If ignorews is (given and) True, then differences
  31   in whitespace do not count, except that there must be no
  32   extra whitespace following token itself.
  33
  34 find_token_exact(lines, token, start[, end]):
  35   As find_token, but with ignorews True.
  36
  37 find_tokens(lines, tokens, start[, end[, ignorews]]):
  38   Returns the first line i, start <= i < end, on which
  39   oen of the tokens in tokens is found at the beginning.
  40   Returns -1 if not found.
  41   If ignorews is (given and) True, then differences
  42   in whitespace do not count, except that there must be no
  43   extra whitespace following token itself.
  44
  45 find_tokens_exact(lines, token, start[, end]):
  46   As find_tokens, but with ignorews True.
  47
  48 find_token_backwards(lines, token, start):
  49 find_tokens_backwards(lines, tokens, start):
  50   As before, but look backwards.
  51
  52 find_re(lines, rexp, start[, end]):
  53   As find_token, but rexp is a regular expression object,
  54   so it has to be passed as e.g.: re.compile(r'...').
  55
  56 get_value(lines, token, start[, end[, default]):
  57   Similar to find_token, but it returns what follows the
  58   token on the found line. Example:
  59     get_value(document.header, "\use_xetex", 0)
  60   will find a line like:
  61     \use_xetex true
  62   and, in that case, return "true". (Note that whitespace
  63   is stripped.) The final argument, default, defaults to "",
  64   and is what is returned if we do not find anything. So you
  65   can use that to set a default.
  66
  67 get_quoted_value(lines, token, start[, end[, default]):
  68   Similar to get_value, but it will strip quotes off the
  69   value, if they are present. So use this one for cases
  70   where the value is normally quoted.
  71
  72 get_option_value(line, option):
  73   This assumes we have a line with something like:
  74       option="value"
  75   and returns value. Returns "" if not found.
  76
  77 del_token(lines, token, start[, end]):
  78   Like find_token, but deletes the line if it finds one.
  79   Returns True if a line got deleted, otherwise False.
  80
  81 find_beginning_of(lines, i, start_token, end_token):
  82   Here, start_token and end_token are meant to be a matching
  83   pair, like "\begin_layout" and "\end_layout". We look for
  84   the start_token that pairs with the end_token that occurs
  85   on or after line i. Returns -1 if not found.
  86   So, in the layout case, this would find the \begin_layout
  87   for the layout line i is in.
  88   Example:
  89     ec = find_token(document.body, "</cell", i)
  90     bc = find_beginning_of(document.body, ec, \
  91         "<cell", "</cell")
  92   Now, assuming no -1s, bc-ec wraps the cell for line i.
  93
  94 find_end_of(lines, i, start_token, end_token):
  95   Like find_beginning_of, but looking for the matching
  96   end_token. This might look like:
  97     bc = find_token_(document.body, "<cell", i)
  98     ec = find_end_of(document.body, bc,  "<cell", "</cell")
  99   Now, assuming no -1s, bc-ec wrap the next cell.
 100
 101 find_end_of_inset(lines, i):
 102   Specialization of find_end_of for insets.
 103
 104 find_end_of_layout(lines, i):
 105   Specialization of find_end_of for layouts.
 106
 107 find_end_of_sequence(lines, i):
 108   Find the end of the sequence of layouts of the same kind.
 109   Considers nesting. If the last paragraph in sequence is nested,
 110   the position of the last \end_deeper is returned, else
 111   the position of the last \end_layout.
 112
 113 is_in_inset(lines, i, inset):
 114   Checks if line i is in an inset of the given type.
 115   If so, returns starting and ending lines. Otherwise,
 116   returns False.
 117   Example:
 118     is_in_inset(document.body, i, "\\begin_inset Tabular")
 119   returns False unless i is within a table. If it is, then
 120   it returns the line on which the table begins and the one
 121   on which it ends. Note that this pair will evaulate to
 122   boolean True, so
 123     if is_in_inset(...):
 124   will do what you expect.
 125
 126 get_containing_inset(lines, i):
 127   Finds out what kind of inset line i is within. Returns a
 128   list containing what follows \begin_inset on the line
 129   on which the inset begins, plus the starting and ending line.
 130   Returns False on any kind of error or if it isn't in an inset.
 131   So get_containing_inset(document.body, i) might return:
 132     ("CommandInset ref", 300, 306)
 133   if i is within an InsetRef beginning on line 300 and ending
 134   on line 306.
 135
 136 get_containing_layout(lines, i):
 137   As get_containing_inset, but for layout. Additionally returns the
 138   position of real paragraph start (after par params) as 4th value.
 139
 140
 141 find_nonempty_line(lines, start[, end):
 142   Finds the next non-empty line.
 143
 144 check_token(line, token):
 145   Does line begin with token?
 146
 147 is_nonempty_line(line):
 148   Does line contain something besides whitespace?
 149
 150 count_pars_in_inset(lines, i):
 151   Counts the paragraphs inside an inset.
 152
 153 '''
 154
 155 import re
 156
 157 # Utilities for one line
 158 def check_token(line, token):
 159     """ check_token(line, token) -> bool
 160
 161     Return True if token is present in line and is the first element
 162     else returns False."""
 163
 164     return line[:len(token)] == token
 165
 166
 167 def is_nonempty_line(line):
 168     """ is_nonempty_line(line) -> bool
 169
 170     Return False if line is either empty or it has only whitespaces,
 171     else return True."""
 172     return line != " "*len(line)
 173
 174
 175 # Utilities for a list of lines
 176 def find_token(lines, token, start, end = 0, ignorews = False):
 177     """ find_token(lines, token, start[[, end], ignorews]) -> int
 178
 179     Return the lowest line where token is found, and is the first
 180     element, in lines[start, end].
 181
 182     If ignorews is True (default is False), then differences in
 183     whitespace are ignored, except that there must be no extra
 184     whitespace following token itself.
 185
 186     Return -1 on failure."""
 187
 188     if end == 0 or end > len(lines):
 189         end = len(lines)
 190     m = len(token)
 191     for i in xrange(start, end):
 192         if ignorews:
 193             x = lines[i].split()
 194             y = token.split()
 195             if len(x) < len(y):
 196                 continue
 197             if x[:len(y)] == y:
 198                 return i
 199         else:
 200             if lines[i][:m] == token:
 201                 return i
 202     return -1
 203
 204
 205 def find_token_exact(lines, token, start, end = 0):
 206     return find_token(lines, token, start, end, True)
 207
 208
 209 def find_tokens(lines, tokens, start, end = 0, ignorews = False):
 210     """ find_tokens(lines, tokens, start[[, end], ignorews]) -> int
 211
 212     Return the lowest line where one token in tokens is found, and is
 213     the first element, in lines[start, end].
 214
 215     Return -1 on failure."""
 216     if end == 0 or end > len(lines):
 217         end = len(lines)
 218
 219     for i in xrange(start, end):
 220         for token in tokens:
 221             if ignorews:
 222                 x = lines[i].split()
 223                 y = token.split()
 224                 if len(x) < len(y):
 225                     continue
 226                 if x[:len(y)] == y:
 227                     return i
 228             else:
 229                 if lines[i][:len(token)] == token:
 230                     return i
 231     return -1
 232
 233
 234 def find_tokens_exact(lines, tokens, start, end = 0):
 235     return find_tokens(lines, tokens, start, end, True)
 236
 237
 238 def find_re(lines, rexp, start, end = 0):
 239     """ find_token_re(lines, rexp, start[, end]) -> int
 240
 241     Return the lowest line where rexp, a regular expression, is found
 242     in lines[start, end].
 243
 244     Return -1 on failure."""
 245
 246     if end == 0 or end > len(lines):
 247         end = len(lines)
 248     for i in xrange(start, end):
 249         if rexp.match(lines[i]):
 250                 return i
 251     return -1
 252
 253
 254 def find_token_backwards(lines, token, start):
 255     """ find_token_backwards(lines, token, start) -> int
 256
 257     Return the highest line where token is found, and is the first
 258     element, in lines[start, end].
 259
 260     Return -1 on failure."""
 261     m = len(token)
 262     for i in xrange(start, -1, -1):
 263         line = lines[i]
 264         if line[:m] == token:
 265             return i
 266     return -1
 267
 268
 269 def find_tokens_backwards(lines, tokens, start):
 270     """ find_tokens_backwards(lines, token, start) -> int
 271
 272     Return the highest line where token is found, and is the first
 273     element, in lines[end, start].
 274
 275     Return -1 on failure."""
 276     for i in xrange(start, -1, -1):
 277         line = lines[i]
 278         for token in tokens:
 279             if line[:len(token)] == token:
 280                 return i
 281     return -1
 282
 283
 284 def get_value(lines, token, start, end = 0, default = ""):
 285     """ get_value(lines, token, start[[, end], default]) -> string
 286
 287     Find the next line that looks like:
 288       token followed by other stuff
 289     Returns "followed by other stuff" with leading and trailing
 290     whitespace removed.
 291     """
 292
 293     i = find_token_exact(lines, token, start, end)
 294     if i == -1:
 295         return default
 296     l = lines[i].split(None, 1)
 297     if len(l) > 1:
 298         return l[1].strip()
 299     return default
 300
 301
 302 def get_quoted_value(lines, token, start, end = 0, default = ""):
 303     """ get_quoted_value(lines, token, start[[, end], default]) -> string
 304
 305     Find the next line that looks like:
 306       token "followed by other stuff"
 307     Returns "followed by other stuff" with leading and trailing
 308     whitespace and quotes removed. If there are no quotes, that is OK too.
 309     So use get_value to preserve possible quotes, this one to remove them,
 310     if they are there.
 311     Note that we will NOT strip quotes from default!
 312     """
 313     val = get_value(lines, token, start, end, "")
 314     if not val:
 315       return default
 316     return val.strip('"')
 317
 318
 319 def get_option_value(line, option):
 320     rx = option + '\s*=\s*"([^"]+)"'
 321     rx = re.compile(rx)
 322     m = rx.search(line)
 323     if not m:
 324       return ""
 325     return m.group(1)
 326
 327
 328 def set_option_value(line, option, value):
 329     rx = '(' + option + '\s*=\s*")[^"]+"'
 330     rx = re.compile(rx)
 331     m = rx.search(line)
 332     if not m:
 333         return line
 334     return re.sub(rx, '\g<1>' + value + '"', line)
 335
 336
 337 def del_token(lines, token, start, end = 0):
 338     """ del_token(lines, token, start, end) -> int
 339
 340     Find the first line in lines where token is the first element
 341     and delete that line. Returns True if we deleted a line, False
 342     if we did not."""
 343
 344     k = find_token_exact(lines, token, start, end)
 345     if k == -1:
 346         return False
 347     del lines[k]
 348     return True
 349
 350
 351 def find_beginning_of(lines, i, start_token, end_token):
 352     count = 1
 353     while i > 0:
 354         i = find_tokens_backwards(lines, [start_token, end_token], i-1)
 355         if i == -1:
 356             return -1
 357         if check_token(lines[i], end_token):
 358             count = count+1
 359         else:
 360             count = count-1
 361         if count == 0:
 362             return i
 363     return -1
 364
 365
 366 def find_end_of(lines, i, start_token, end_token):
 367     count = 1
 368     n = len(lines)
 369     while i < n:
 370         i = find_tokens(lines, [end_token, start_token], i+1)
 371         if i == -1:
 372             return -1
 373         if check_token(lines[i], start_token):
 374             count = count+1
 375         else:
 376             count = count-1
 377         if count == 0:
 378             return i
 379     return -1
 380
 381
 382 def find_nonempty_line(lines, start, end = 0):
 383     if end == 0:
 384         end = len(lines)
 385     for i in xrange(start, end):
 386         if is_nonempty_line(lines[i]):
 387             return i
 388     return -1
 389
 390
 391 def find_end_of_inset(lines, i):
 392     " Find end of inset, where lines[i] is included."
 393     return find_end_of(lines, i, "\\begin_inset", "\\end_inset")
 394
 395
 396 def find_end_of_layout(lines, i):
 397     " Find end of layout, where lines[i] is included."
 398     return find_end_of(lines, i, "\\begin_layout", "\\end_layout")
 399
 400
 401 def is_in_inset(lines, i, inset):
 402     '''
 403     Checks if line i is in an inset of the given type.
 404     If so, returns starting and ending lines.
 405     Otherwise, returns False.
 406     Example:
 407       is_in_inset(document.body, i, "\\begin_inset Tabular")
 408     returns False unless i is within a table. If it is, then
 409     it returns the line on which the table begins and the one
 410     on which it ends. Note that this pair will evaulate to
 411     boolean True, so
 412       if is_in_inset(...):
 413     will do what you expect.
 414     '''
 415     defval = (-1, -1)
 416     stins = find_token_backwards(lines, inset, i)
 417     if stins == -1:
 418       return defval
 419     endins = find_end_of_inset(lines, stins)
 420     # note that this includes the notfound case.
 421     if endins < i:
 422       return defval
 423     return (stins, endins)
 424
 425
 426 def get_containing_inset(lines, i):
 427   '''
 428   Finds out what kind of inset line i is within. Returns a
 429   list containing (i) what follows \begin_inset on the line
 430   on which the inset begins, plus the starting and ending line.
 431   Returns False on any kind of error or if it isn't in an inset.
 432   '''
 433   j = i
 434   while True:
 435       stins = find_token_backwards(lines, "\\begin_inset", j)
 436       if stins == -1:
 437           return False
 438       endins = find_end_of_inset(lines, stins)
 439       if endins > j:
 440           break
 441       j = stins - 1
 442
 443   inset = get_value(lines, "\\begin_inset", stins)
 444   if inset == "":
 445       # shouldn't happen
 446       return False
 447   return (inset, stins, endins)
 448
 449
 450 def get_containing_layout(lines, i):
 451   '''
 452   Finds out what kind of layout line i is within. Returns a
 453   list containing (i) what follows \begin_layout on the line
 454   on which the layout begins, plus the starting and ending line
 455   and the start of the apargraph (after all params).
 456   Returns False on any kind of error.
 457   '''
 458   j = i
 459   while True:
 460       stlay = find_token_backwards(lines, "\\begin_layout", j)
 461       if stlay == -1:
 462           return False
 463       endlay = find_end_of_layout(lines, stlay)
 464       if endlay > i:
 465           break
 466       j = stlay - 1
 467
 468   lay = get_value(lines, "\\begin_layout", stlay)
 469   if lay == "":
 470       # shouldn't happen
 471       return False
 472   par_params = ["\\noindent", "\\indent", "\\indent-toggle", "\\leftindent",
 473                 "\\start_of_appendix", "\\paragraph_spacing single",
 474                 "\\paragraph_spacing onehalf", "\\paragraph_spacing double",
 475                 "\\paragraph_spacing other", "\\align", "\\labelwidthstring"]
 476   stpar = stlay
 477   while True:
 478       stpar += 1
 479       if lines[stpar] not in par_params:
 480           break
 481   return (lay, stlay, endlay, stpar)
 482
 483
 484 def count_pars_in_inset(lines, i):
 485   '''
 486   Counts the paragraphs within this inset
 487   '''
 488   ins = get_containing_inset(lines, i)
 489   if ins == -1:
 490       return -1
 491   pars = 0
 492   for j in range(ins[1], ins[2]):
 493       m = re.match(r'\\begin_layout (.*)', lines[j])
 494       if m and get_containing_inset(lines, j)[0] == ins[0]:
 495           pars += 1
 496
 497   return pars
 498
 499
 500 def find_end_of_sequence(lines, i):
 501   '''
 502   Returns the end of a sequence of identical layouts.
 503   '''
 504   lay = get_containing_layout(lines, i)
 505   if lay == False:
 506       return -1
 507   layout = lay[0]
 508   endlay = lay[2]
 509   i = endlay
 510   while True:
 511       m = re.match(r'\\begin_layout (.*)', lines[i])
 512       if m and m.group(1) != layout:
 513           return endlay
 514       elif lines[i] == "\\begin_deeper":
 515           j = find_end_of(lines, i, "\\begin_deeper", "\\end_deeper")
 516           if j != -1:
 517               i = j
 518               endlay = j
 519               continue
 520       if m and m.group(1) == layout:
 521           endlay = find_end_of_layout(lines, i)
 522           i = endlay
 523           continue
 524       if i == len(lines) - 1:
 525           break
 526       i = i + 1
 527
 528   return endlay
 529