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>
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.
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.
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
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.
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
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.
34 find_token_exact(lines, token, start[, end]):
35 As find_token, but with ignorews True.
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.
45 find_tokens_exact(lines, token, start[, end]):
46 As find_tokens, but with ignorews True.
48 find_token_backwards(lines, token, start):
49 find_tokens_backwards(lines, tokens, start):
50 As before, but look backwards.
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'...').
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:
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.
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.
72 get_option_value(line, option):
73 This assumes we have a line with something like:
75 and returns value. Returns "" if not found.
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.
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.
89 ec = find_token(document.body, "</cell", i)
90 bc = find_beginning_of(document.body, ec, \
92 Now, assuming no -1s, bc-ec wraps the cell for line i.
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.
101 find_end_of_inset(lines, i):
102 Specialization of find_end_of for insets.
104 find_end_of_layout(lines, i):
105 Specialization of find_end_of for layouts.
107 is_in_inset(lines, i, inset):
108 Checks if line i is in an inset of the given type.
109 If so, returns starting and ending lines. Otherwise,
112 is_in_inset(document.body, i, "\\begin_inset Tabular")
113 returns False unless i is within a table. If it is, then
114 it returns the line on which the table begins and the one
115 on which it ends. Note that this pair will evaulate to
118 will do what you expect.
120 get_containing_inset(lines, i):
121 Finds out what kind of inset line i is within. Returns a
122 list containing what follows \begin_inset on the the line
123 on which the inset begins, plus the starting and ending line.
124 Returns False on any kind of error or if it isn't in an inset.
125 So get_containing_inset(document.body, i) might return:
126 ("CommandInset ref", 300, 306)
127 if i is within an InsetRef beginning on line 300 and ending
130 get_containing_layout(lines, i):
131 As get_containing_inset, but for layout.
134 find_nonempty_line(lines, start[, end):
135 Finds the next non-empty line.
137 check_token(line, token):
138 Does line begin with token?
140 is_nonempty_line(line):
141 Does line contain something besides whitespace?
147 # Utilities for one line
148 def check_token(line, token):
149 """ check_token(line, token) -> bool
151 Return True if token is present in line and is the first element
152 else returns False."""
154 return line[:len(token)] == token
157 def is_nonempty_line(line):
158 """ is_nonempty_line(line) -> bool
160 Return False if line is either empty or it has only whitespaces,
162 return line != " "*len(line)
165 # Utilities for a list of lines
166 def find_token(lines, token, start, end = 0, ignorews = False):
167 """ find_token(lines, token, start[[, end], ignorews]) -> int
169 Return the lowest line where token is found, and is the first
170 element, in lines[start, end].
172 If ignorews is True (default is False), then differences in
173 whitespace are ignored, except that there must be no extra
174 whitespace following token itself.
176 Return -1 on failure."""
178 if end == 0 or end > len(lines):
181 for i in xrange(start, end):
190 if lines[i][:m] == token:
195 def find_token_exact(lines, token, start, end = 0):
196 return find_token(lines, token, start, end, True)
199 def find_tokens(lines, tokens, start, end = 0, ignorews = False):
200 """ find_tokens(lines, tokens, start[[, end], ignorews]) -> int
202 Return the lowest line where one token in tokens is found, and is
203 the first element, in lines[start, end].
205 Return -1 on failure."""
206 if end == 0 or end > len(lines):
209 for i in xrange(start, end):
219 if lines[i][:len(token)] == token:
224 def find_tokens_exact(lines, tokens, start, end = 0):
225 return find_tokens(lines, tokens, start, end, True)
228 def find_re(lines, rexp, start, end = 0):
229 """ find_token_re(lines, rexp, start[, end]) -> int
231 Return the lowest line where rexp, a regular expression, is found
232 in lines[start, end].
234 Return -1 on failure."""
236 if end == 0 or end > len(lines):
238 for i in xrange(start, end):
239 if rexp.match(lines[i]):
244 def find_token_backwards(lines, token, start):
245 """ find_token_backwards(lines, token, start) -> int
247 Return the highest line where token is found, and is the first
248 element, in lines[start, end].
250 Return -1 on failure."""
252 for i in xrange(start, -1, -1):
254 if line[:m] == token:
259 def find_tokens_backwards(lines, tokens, start):
260 """ find_tokens_backwards(lines, token, start) -> int
262 Return the highest line where token is found, and is the first
263 element, in lines[end, start].
265 Return -1 on failure."""
266 for i in xrange(start, -1, -1):
269 if line[:len(token)] == token:
274 def get_value(lines, token, start, end = 0, default = ""):
275 """ get_value(lines, token, start[[, end], default]) -> string
277 Find the next line that looks like:
278 token followed by other stuff
279 Returns "followed by other stuff" with leading and trailing
283 i = find_token_exact(lines, token, start, end)
286 l = lines[i].split(None, 1)
292 def get_quoted_value(lines, token, start, end = 0, default = ""):
293 """ get_quoted_value(lines, token, start[[, end], default]) -> string
295 Find the next line that looks like:
296 token "followed by other stuff"
297 Returns "followed by other stuff" with leading and trailing
298 whitespace and quotes removed. If there are no quotes, that is OK too.
299 So use get_value to preserve possible quotes, this one to remove them,
301 Note that we will NOT strip quotes from default!
303 val = get_value(lines, token, start, end, "")
306 return val.strip('"')
309 def get_option_value(line, option):
310 rx = option + '\s*=\s*"([^"]+)"'
318 def del_token(lines, token, start, end = 0):
319 """ del_token(lines, token, start, end) -> int
321 Find the first line in lines where token is the first element
322 and delete that line. Returns True if we deleted a line, False
325 k = find_token_exact(lines, token, start, end)
332 def find_beginning_of(lines, i, start_token, end_token):
335 i = find_tokens_backwards(lines, [start_token, end_token], i-1)
338 if check_token(lines[i], end_token):
347 def find_end_of(lines, i, start_token, end_token):
351 i = find_tokens(lines, [end_token, start_token], i+1)
354 if check_token(lines[i], start_token):
363 def find_nonempty_line(lines, start, end = 0):
366 for i in xrange(start, end):
367 if is_nonempty_line(lines[i]):
372 def find_end_of_inset(lines, i):
373 " Find end of inset, where lines[i] is included."
374 return find_end_of(lines, i, "\\begin_inset", "\\end_inset")
377 def find_end_of_layout(lines, i):
378 " Find end of layout, where lines[i] is included."
379 return find_end_of(lines, i, "\\begin_layout", "\\end_layout")
382 def is_in_inset(lines, i, inset):
384 Checks if line i is in an inset of the given type.
385 If so, returns starting and ending lines.
386 Otherwise, returns False.
388 is_in_inset(document.body, i, "\\begin_inset Tabular")
389 returns False unless i is within a table. If it is, then
390 it returns the line on which the table begins and the one
391 on which it ends. Note that this pair will evaulate to
394 will do what you expect.
397 stins = find_token_backwards(lines, inset, i)
400 endins = find_end_of_inset(lines, stins)
401 # note that this includes the notfound case.
404 return (stins, endins)
407 def get_containing_inset(lines, i):
409 Finds out what kind of inset line i is within. Returns a
410 list containing (i) what follows \begin_inset on the the line
411 on which the inset begins, plus the starting and ending line.
412 Returns False on any kind of error or if it isn't in an inset.
414 stins = find_token_backwards(lines, i, "\\begin_inset")
417 endins = find_end_of_inset(lines, stins)
420 inset = get_value(lines, "\\begin_inset", stins)
424 return (inset, stins, endins)
427 def get_containing_layout(lines, i):
429 Finds out what kind of layout line i is within. Returns a
430 list containing (i) what follows \begin_layout on the the line
431 on which the layout begins, plus the starting and ending line.
432 Returns False on any kind of error.
434 stins = find_token_backwards(lines, i, "\\begin_layout")
437 endins = find_end_of_layout(lines, stins)
440 lay = get_value(lines, "\\begin_layout", stins)
444 return (lay, stins, endins)