Parses a line (a string) as a representation of a list. Can recursively parse nested lists. (List members can themselves be lists). List elements are stripped - and are returned as either lists or strings. This is useful for storing lists of information as text - for example in config files
(inline, recursive = 1, comment = 1, retain = 0, lpstack = None, **keywargs)
| 5 | # Used by COnfigObj for storing config files with lists of values. |
| 6 | |
| 7 | def listparse(inline, recursive = 1, comment = 1, retain = 0, lpstack = None, **keywargs): |
| 8 | """Parses a line (a string) as a representation of a list. Can recursively parse nested lists. (List members can themselves be lists). |
| 9 | List elements are stripped - and are returned as either lists or strings. |
| 10 | |
| 11 | This is useful for storing lists of information as text - for example in config files |
| 12 | |
| 13 | Listparse returns the list and trailing comments or None if the list is badly built. |
| 14 | |
| 15 | A valid comments exists after the end of the list (and any whitespace) and starts with a '#' or a ';'. |
| 16 | Returned comment will include the initial '#' or a ';'. |
| 17 | |
| 18 | Commas delimit list elements. |
| 19 | If the first non whitespace character in a list element is '[' then that element is treated as a list. |
| 20 | |
| 21 | Inside the list '[', ']', '"', "\" or '\' can be escaped with '\' |
| 22 | (or indeed any other character - a single '\' will always be treated as escaping the character that follows) |
| 23 | The leading '\' of escaped characters is *not* retained..... |
| 24 | Any unquoted list elements must not have an unescaped ']' in them - except to terminate the current list. |
| 25 | Escaping can be switched off by passing in a keyword argument 'escapechar' set to None. |
| 26 | If you want to use literal '\' without escaping them - then you must switch escaping off. |
| 27 | If you make sure every element of a list is contained within quotes - using the quot_elem function - this shouldn't be a problem). |
| 28 | |
| 29 | If retain is set to 1 (default is 0) any quotes around elements will be retained. |
| 30 | This could be used to specify element types - e.g. if it has quotes it is a string. |
| 31 | So the function unquote can be used recursively to check if a list element is validly quoted. |
| 32 | (and here you could implement other methods for unquoted elements - e.g. check for None or integer values etc...) |
| 33 | *However* if an element is quoted - it must be correctly quoted, or the element will be invalid. |
| 34 | The default is for quotes to be removed. |
| 35 | |
| 36 | If recursive is set to 0 (default is 1) |
| 37 | then list elements will not be recursively parsed - an element containing another list will just |
| 38 | be returned as a string. |
| 39 | (meaning an unescaped and unquoted ']' will close the current list... and listparse will say you have a bad list). |
| 40 | |
| 41 | lpstack is used for recursion. Effectively it parses the current table and returns the rest of the line as well. |
| 42 | |
| 43 | If comment is set to 0 (default is 1) |
| 44 | It causes listparse to return None if there is anything other than whitespace after a valid list. |
| 45 | (I.e. comments are not allowed). In this case it will only return the list. |
| 46 | """ |
| 47 | if keywargs.has_key('escapechar'): |
| 48 | escapechar = keywargs['escapechar'] # either True or False |
| 49 | else: |
| 50 | escapechar = True |
| 51 | outlist = [] |
| 52 | inline = inline.strip() |
| 53 | if inline[0] != '[': |
| 54 | return None |
| 55 | inline = inline[1:].lstrip() |
| 56 | found_end = 0 |
| 57 | thiselement = None |
| 58 | escape = 0 |
| 59 | while inline: |
| 60 | if thiselement == None: # start of the element |
| 61 | output = unquote(inline, 0, retain, escapechar=escapechar) # partquote mode, retain quotes....... |
| 62 | if output == None: |
| 63 | return None |
| 64 | if output != -1: # element is quoted |