Source Code for Module lib.text.string

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2010-2012,2019 Edward d'Auvergne                              # 
  4  #                                                                             # 
  5  # This file is part of the program relax (http://www.nmr-relax.com).          # 
  6  #                                                                             # 
  7  # This program is free software: you can redistribute it and/or modify        # 
  8  # it under the terms of the GNU General Public License as published by        # 
  9  # the Free Software Foundation, either version 3 of the License, or           # 
 10  # (at your option) any later version.                                         # 
 11  #                                                                             # 
 12  # This program is distributed in the hope that it will be useful,             # 
 13  # but WITHOUT ANY WARRANTY; without even the implied warranty of              # 
 14  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the               # 
 15  # GNU General Public License for more details.                                # 
 16  #                                                                             # 
 17  # You should have received a copy of the GNU General Public License           # 
 18  # along with this program.  If not, see <http://www.gnu.org/licenses/>.       # 
 19  #                                                                             # 
 20  ############################################################################### 
 21   
 22  # Module docstring. 
 23  """Module for building documentation.""" 
 24   
 25  # Python module imports. 
 26  from copy import deepcopy 
 27   
 28   
 29  # Some constants. 
 30  TITLE = 3 
 31  SECTION = 2 
 32  SUBSECTION = 1 
 33  PARAGRAPH = 0 
 34  LIST = 10 
 35   
 36   
 37 -def human_readable_list(data, conjunction="and"): 
 38      """Convert the list/array object into a human readable list. 
 39   
 40      This formats and returns a list, with the last element prefixed with the qualifier. 
 41   
 42   
 43      @param data:            The list or array object to convert. 
 44      @type data:             list of str 
 45      @keyword conjunction:   The conjunction to add to the list. 
 46      @type conjunction:      str 
 47      @return:                The formatted list. 
 48      @rtype:                 str 
 49      """ 
 50   
 51      # Avoid modifying the original list. 
 52      new_data = deepcopy(data) 
 53   
 54      # Handle an empty list or a single element. 
 55      if len(data) == 0: 
 56          string = "" 
 57      elif len(data) == 1: 
 58          string = data[0] 
 59   
 60      # Two elements. 
 61      elif len(data) == 2: 
 62          string = "%s %s %s" % (data[0], conjunction, data[1]) 
 63   
 64      # Multiple elements. 
 65      else: 
 66          string = "%s" % data[0] 
 67          for i in range(1, len(data) - 1): 
 68              string += ", %s" % data[i] 
 69          string += ", %s %s" % (conjunction, data[-1]) 
 70   
 71      # Return the formatted list. 
 72      return string 
 73   
 74   
 75 -def strip_lead(text): 
 76      """Strip the leading whitespace from the given text. 
 77   
 78      @param text:    The text to strip the leading whitespace from. 
 79      @type text:     str 
 80      @return:        The text with leading whitespace removed. 
 81      @rtype:         str 
 82      """ 
 83   
 84      # Split by newline. 
 85      lines = text.split('\n') 
 86   
 87      # Find the minimum whitespace. 
 88      min_white = 1000 
 89      for line in lines: 
 90          # Empty lines. 
 91          if line.strip() == '': 
 92              continue 
 93   
 94          # Count the whitespace for the current line. 
 95          num_white = 0 
 96          for i in range(len(line)): 
 97              if line[i] != ' ': 
 98                  break 
 99              num_white = num_white + 1 
100   
101          # The min value. 
102          min_white = min(min_white, num_white) 
103   
104      # Strip the whitespace. 
105      new_text = '' 
106      for line in lines: 
107          new_text = new_text + line[min_white:] + '\n' 
108   
109      # Return the new text. 
110      return new_text 
111   
112   
113 -def to_docstring(data): 
114      """Convert the text to that of a docstring, dependent on the text level. 
115   
116      @param data:    The lists of constants and text to convert into a properly formatted docstring. 
117      @type data:     list of lists of int and str 
118      """ 
119   
120      # Init. 
121      doc = '' 
122      for i in range(len(data)): 
123          # The level and text. 
124          level, text = data[i] 
125   
126          # Title level. 
127          if level == TITLE: 
128              doc += text + '\n\n' 
129   
130          # Section level. 
131          if level == SECTION: 
132              doc += '\n\n' + text + '\n' + '='*len(text) + '\n\n' 
133   
134          # Subsection level. 
135          if level == SUBSECTION: 
136              doc += '\n\n' + text + '\n' + '-'*len(text) + '\n\n' 
137   
138          # Paragraph level. 
139          elif level == PARAGRAPH: 
140              # Starting newline. 
141              if i and data[i-1][0] == PARAGRAPH: 
142                  doc += '\n' 
143   
144              # The text. 
145              doc += text + '\n' 
146   
147          # List level. 
148          elif level == LIST: 
149              # Start of list. 
150              if i and data[i-1][0] != LIST: 
151                  doc += '\n' 
152   
153              # The text. 
154              doc += "    - %s\n" % text 
155   
156              # End of list. 
157              if i < len(data) and data[i+1][0] == PARAGRAPH: 
158                  doc += '\n' 
159   
160      # Return the docstring. 
161      return doc 
162