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.
 110
 111 is_in_inset(lines, i, inset):
 112   Checks if line i is in an inset of the given type.
 113   If so, returns starting and ending lines. Otherwise,
 114   returns False.
 115   Example:
 116     is_in_inset(document.body, i, "\\begin_inset Tabular")
 117   returns False unless i is within a table. If it is, then
 118   it returns the line on which the table begins and the one
 119   on which it ends. Note that this pair will evaulate to
 120   boolean True, so
 121     if is_in_inset(...):
 122   will do what you expect.
 123
 124 get_containing_inset(lines, i):
 125   Finds out what kind of inset line i is within. Returns a
 126   list containing what follows \begin_inset on the the line
 127   on which the inset begins, plus the starting and ending line.
 128   Returns False on any kind of error or if it isn't in an inset.
 129   So get_containing_inset(document.body, i) might return:
 130     ("CommandInset ref", 300, 306)
 131   if i is within an InsetRef beginning on line 300 and ending
 132   on line 306.
 133
 134 get_containing_layout(lines, i):
 135   As get_containing_inset, but for layout. Additionally returns the
 136   position of real paragraph start (after par params) as 4th value.
 137
 138
 139 find_nonempty_line(lines, start[, end):
 140   Finds the next non-empty line.
 141
 142 check_token(line, token):
 143   Does line begin with token?
 144
 145 is_nonempty_line(line):
 146   Does line contain something besides whitespace?
 147
 148 count_pars_in_inset(lines, i):
 149   Counts the paragraphs inside an inset.
 150
 151 '''
 152
 153 import re
 154
 155 # Utilities for one line
 156 def check_token(line, token):
 157     """ check_token(line, token) -> bool
 158
 159     Return True if token is present in line and is the first element
 160     else returns False."""
 161
 162     return line[:len(token)] == token
 163
 164
 165 def is_nonempty_line(line):
 166     """ is_nonempty_line(line) -> bool
 167
 168     Return False if line is either empty or it has only whitespaces,
 169     else return True."""
 170     return line != " "*len(line)
 171
 172
 173 # Utilities for a list of lines
 174 def find_token(lines, token, start, end = 0, ignorews = False):
 175     """ find_token(lines, token, start[[, end], ignorews]) -> int
 176
 177     Return the lowest line where token is found, and is the first
 178     element, in lines[start, end].
 179
 180     If ignorews is True (default is False), then differences in
 181     whitespace are ignored, except that there must be no extra
 182     whitespace following token itself.
 183
 184     Return -1 on failure."""
 185
 186     if end == 0 or end > len(lines):
 187         end = len(lines)
 188     m = len(token)
 189     for i in xrange(start, end):
 190         if ignorews:
 191             x = lines[i].split()
 192             y = token.split()
 193             if len(x) < len(y):
 194                 continue
 195             if x[:len(y)] == y:
 196                 return i
 197         else:
 198             if lines[i][:m] == token:
 199                 return i
 200     return -1
 201
 202
 203 def find_token_exact(lines, token, start, end = 0):
 204     return find_token(lines, token, start, end, True)
 205
 206
 207 def find_tokens(lines, tokens, start, end = 0, ignorews = False):
 208     """ find_tokens(lines, tokens, start[[, end], ignorews]) -> int
 209
 210     Return the lowest line where one token in tokens is found, and is
 211     the first element, in lines[start, end].
 212
 213     Return -1 on failure."""
 214     if end == 0 or end > len(lines):
 215         end = len(lines)
 216
 217     for i in xrange(start, end):
 218         for token in tokens:
 219             if ignorews:
 220                 x = lines[i].split()
 221                 y = token.split()
 222                 if len(x) < len(y):
 223                     continue
 224                 if x[:len(y)] == y:
 225                     return i
 226             else:
 227                 if lines[i][:len(token)] == token:
 228                     return i
 229     return -1
 230
 231
 232 def find_tokens_exact(lines, tokens, start, end = 0):
 233     return find_tokens(lines, tokens, start, end, True)
 234
 235
 236 def find_re(lines, rexp, start, end = 0):
 237     """ find_token_re(lines, rexp, start[, end]) -> int
 238
 239     Return the lowest line where rexp, a regular expression, is found
 240     in lines[start, end].
 241
 242     Return -1 on failure."""
 243
 244     if end == 0 or end > len(lines):
 245         end = len(lines)
 246     for i in xrange(start, end):
 247         if rexp.match(lines[i]):
 248                 return i
 249     return -1
 250
 251
 252 def find_token_backwards(lines, token, start):
 253     """ find_token_backwards(lines, token, start) -> int
 254
 255     Return the highest line where token is found, and is the first
 256     element, in lines[start, end].
 257
 258     Return -1 on failure."""
 259     m = len(token)
 260     for i in xrange(start, -1, -1):
 261         line = lines[i]
 262         if line[:m] == token:
 263             return i
 264     return -1
 265
 266
 267 def find_tokens_backwards(lines, tokens, start):
 268     """ find_tokens_backwards(lines, token, start) -> int
 269
 270     Return the highest line where token is found, and is the first
 271     element, in lines[end, start].
 272
 273     Return -1 on failure."""
 274     for i in xrange(start, -1, -1):
 275         line = lines[i]
 276         for token in tokens:
 277             if line[:len(token)] == token:
 278                 return i
 279     return -1
 280
 281
 282 def get_value(lines, token, start, end = 0, default = ""):
 283     """ get_value(lines, token, start[[, end], default]) -> string
 284
 285     Find the next line that looks like:
 286       token followed by other stuff
 287     Returns "followed by other stuff" with leading and trailing
 288     whitespace removed.
 289     """
 290
 291     i = find_token_exact(lines, token, start, end)
 292     if i == -1:
 293         return default
 294     l = lines[i].split(None, 1)
 295     if len(l) > 1:
 296         return l[1].strip()
 297     return default
 298
 299
 300 def get_quoted_value(lines, token, start, end = 0, default = ""):
 301     """ get_quoted_value(lines, token, start[[, end], default]) -> string
 302
 303     Find the next line that looks like:
 304       token "followed by other stuff"
 305     Returns "followed by other stuff" with leading and trailing
 306     whitespace and quotes removed. If there are no quotes, that is OK too.
 307     So use get_value to preserve possible quotes, this one to remove them,
 308     if they are there.
 309     Note that we will NOT strip quotes from default!
 310     """
 311     val = get_value(lines, token, start, end, "")
 312     if not val:
 313       return default
 314     return val.strip('"')
 315
 316
 317 def get_option_value(line, option):
 318     rx = option + '\s*=\s*"([^"]+)"'
 319     rx = re.compile(rx)
 320     m = rx.search(line)
 321     if not m:
 322       return ""
 323     return m.group(1)
 324
 325
 326 def set_option_value(line, option, value):
 327     rx = '(' + option + '\s*=\s*")[^"]+"'
 328     rx = re.compile(rx)
 329     m = rx.search(line)
 330     if not m:
 331         return line
 332     return re.sub(rx, '\g<1>' + value + '"', line)
 333
 334
 335 def del_token(lines, token, start, end = 0):
 336     """ del_token(lines, token, start, end) -> int
 337
 338     Find the first line in lines where token is the first element
 339     and delete that line. Returns True if we deleted a line, False
 340     if we did not."""
 341
 342     k = find_token_exact(lines, token, start, end)
 343     if k == -1:
 344         return False
 345     del lines[k]
 346     return True
 347
 348
 349 def find_beginning_of(lines, i, start_token, end_token):
 350     count = 1
 351     while i > 0:
 352         i = find_tokens_backwards(lines, [start_token, end_token], i-1)
 353         if i == -1:
 354             return -1
 355         if check_token(lines[i], end_token):
 356             count = count+1
 357         else:
 358             count = count-1
 359         if count == 0:
 360             return i
 361     return -1
 362
 363
 364 def find_end_of(lines, i, start_token, end_token):
 365     count = 1
 366     n = len(lines)
 367     while i < n:
 368         i = find_tokens(lines, [end_token, start_token], i+1)
 369         if i == -1:
 370             return -1
 371         if check_token(lines[i], start_token):
 372             count = count+1
 373         else:
 374             count = count-1
 375         if count == 0:
 376             return i
 377     return -1
 378
 379
 380 def find_nonempty_line(lines, start, end = 0):
 381     if end == 0:
 382         end = len(lines)
 383     for i in xrange(start, end):
 384         if is_nonempty_line(lines[i]):
 385             return i
 386     return -1
 387
 388
 389 def find_end_of_inset(lines, i):
 390     " Find end of inset, where lines[i] is included."
 391     return find_end_of(lines, i, "\\begin_inset", "\\end_inset")
 392
 393
 394 def find_end_of_layout(lines, i):
 395     " Find end of layout, where lines[i] is included."
 396     return find_end_of(lines, i, "\\begin_layout", "\\end_layout")
 397
 398
 399 def is_in_inset(lines, i, inset):
 400     '''
 401     Checks if line i is in an inset of the given type.
 402     If so, returns starting and ending lines.
 403     Otherwise, returns False.
 404     Example:
 405       is_in_inset(document.body, i, "\\begin_inset Tabular")
 406     returns False unless i is within a table. If it is, then
 407     it returns the line on which the table begins and the one
 408     on which it ends. Note that this pair will evaulate to
 409     boolean True, so
 410       if is_in_inset(...):
 411     will do what you expect.
 412     '''
 413     defval = (-1, -1)
 414     stins = find_token_backwards(lines, inset, i)
 415     if stins == -1:
 416       return defval
 417     endins = find_end_of_inset(lines, stins)
 418     # note that this includes the notfound case.
 419     if endins < i:
 420       return defval
 421     return (stins, endins)
 422
 423
 424 def get_containing_inset(lines, i):
 425   '''
 426   Finds out what kind of inset line i is within. Returns a
 427   list containing (i) what follows \begin_inset on the the line
 428   on which the inset begins, plus the starting and ending line.
 429   Returns False on any kind of error or if it isn't in an inset.
 430   '''
 431   j = i
 432   while True:
 433       stins = find_token_backwards(lines, "\\begin_inset", j)
 434       if stins == -1:
 435           return False
 436       endins = find_end_of_inset(lines, stins)
 437       if endins > j:
 438           break
 439       j = stins - 1
 440
 441   inset = get_value(lines, "\\begin_inset", stins)
 442   if inset == "":
 443       # shouldn't happen
 444       return False
 445   return (inset, stins, endins)
 446
 447
 448 def get_containing_layout(lines, i):
 449   '''
 450   Finds out what kind of layout line i is within. Returns a
 451   list containing (i) what follows \begin_layout on the the line
 452   on which the layout begins, plus the starting and ending line
 453   and the start of the apargraph (after all params).
 454   Returns False on any kind of error.
 455   '''
 456   j = i
 457   while True:
 458       stlay = find_token_backwards(lines, "\\begin_layout", j)
 459       if stlay == -1:
 460           return False
 461       endlay = find_end_of_layout(lines, stlay)
 462       if endlay > i:
 463           break
 464       j = stlay - 1
 465
 466   lay = get_value(lines, "\\begin_layout", stlay)
 467   if lay == "":
 468       # shouldn't happen
 469       return False
 470   par_params = ["\\noindent", "\\indent", "\\indent-toggle", "\\leftindent",
 471                 "\\start_of_appendix", "\\paragraph_spacing single",
 472                 "\\paragraph_spacing onehalf", "\\paragraph_spacing double",
 473                 "\\paragraph_spacing other", "\\align", "\\labelwidthstring"]
 474   stpar = stlay
 475   while True:
 476       stpar += 1
 477       if lines[stpar] not in par_params:
 478           break
 479   return (lay, stlay, endlay, stpar)
 480
 481
 482 def count_pars_in_inset(lines, i):
 483   '''
 484   Counts the paragraphs within this inset
 485   '''
 486   ins = get_containing_inset(lines, i)
 487   if ins == -1:
 488       return -1
 489   pars = 0
 490   for j in range(ins[1], ins[2]):
 491       m = re.match(r'\\begin_layout (.*)', lines[j])
 492       if m and get_containing_inset(lines, j)[0] == ins[0]:
 493           pars += 1
 494
 495   return pars
 496
 497
 498 def find_end_of_sequence(lines, i):
 499   '''
 500   Returns the end of a sequence of identical layouts.
 501   '''
 502   lay = get_containing_layout(lines, i)
 503   if lay == False:
 504       return -1
 505   layout = lay[0]
 506   endlay = lay[2]
 507   i = endlay
 508   while True:
 509       m = re.match(r'\\begin_layout (.*)', lines[i])
 510       if m and m.group(1) != layout:
 511           return endlay
 512       elif lines[i] == "\\begin_deeper":
 513           j = find_end_of(lines, i, "\\begin_deeper", "\\end_deeper")
 514           if j != -1:
 515               i = j
 516               continue
 517       if m and m.group(1) == layout:
 518           endlay = find_end_of_layout(lines, i)
 519           i = endlay
 520           continue
 521       if i == len(lines) - 1:
 522           break
 523       i = i + 1
 524
 525   return endlay
 526