Source Code for Module lib.text.sectioning

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2013 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  """Functions for the formatting of titles, subtitles and other sectioning.""" 
 24   
 25   
 26 -def box(file=None, text=None, char=None): 
 27      """Format and write out a box surrounding the text. 
 28   
 29      @keyword file:      The file object to write to. 
 30      @type file:         file object 
 31      @keyword text:      The text to box. 
 32      @type text:         str 
 33      @keyword char:      The single character to use for the box. 
 34      @type char:         str 
 35      """ 
 36   
 37      # The length and horizontal box text. 
 38      length = len(text) + 4 
 39      hline = char * length 
 40   
 41      # The text. 
 42      file.write("%s\n" % hline) 
 43      file.write("%s %s %s\n" % (char, text, char)) 
 44      file.write("%s\n" % hline) 
 45   
 46   
 47 -def section(file=None, text=None, prespace=2, postspace=1): 
 48      """Format and write out a section to the given file. 
 49   
 50      @keyword file:      The file object to write to. 
 51      @type file:         file object 
 52      @keyword text:      The section text. 
 53      @type text:         str 
 54      @keyword prespace:  The number of empty lines prior to the text printout. 
 55      @type prespace:     int 
 56      @keyword postspace: The number of empty lines after the text printout. 
 57      @type postspace:    int 
 58      """ 
 59   
 60      # Format the text. 
 61      file.write("\n" * prespace) 
 62      underline(file=file, text=text, char="=") 
 63      file.write("\n" * postspace) 
 64   
 65   
 66 -def subsection(file=None, text=None, prespace=1, postspace=1): 
 67      """Format and write out a subsection to the given file. 
 68   
 69      @keyword file:      The file object to write to. 
 70      @type file:         file object 
 71      @keyword text:      The subsection text. 
 72      @type text:         str 
 73      @keyword prespace:  The number of empty lines prior to the text printout. 
 74      @type prespace:     int 
 75      @keyword postspace: The number of empty lines after the text printout. 
 76      @type postspace:    int 
 77      """ 
 78   
 79      # Format the text. 
 80      file.write("\n" * prespace) 
 81      underline(file=file, text=text, char="-") 
 82      file.write("\n" * postspace) 
 83   
 84   
 85 -def subsubsection(file=None, text=None, prespace=1, postspace=1): 
 86      """Format and write out a subsubsection to the given file. 
 87   
 88      @keyword file:      The file object to write to. 
 89      @type file:         file object 
 90      @keyword text:      The subsubsection text. 
 91      @type text:         str 
 92      @keyword prespace:  The number of empty lines prior to the text printout. 
 93      @type prespace:     int 
 94      @keyword postspace: The number of empty lines after the text printout. 
 95      @type postspace:    int 
 96      """ 
 97   
 98      # Format the text. 
 99      file.write("\n" * prespace) 
100      underline(file=file, text=text, char="~") 
101      file.write("\n" * postspace) 
102   
103   
104 -def subsubtitle(file=None, text=None, prespace=1, postspace=1): 
105      """Format and write out a subsubtitle to the given file. 
106   
107      @keyword file:      The file object to write to. 
108      @type file:         file object 
109      @keyword text:      The subsubtitle text. 
110      @type text:         str 
111      @keyword prespace:  The number of empty lines prior to the text printout. 
112      @type prespace:     int 
113      @keyword postspace: The number of empty lines after the text printout. 
114      @type postspace:    int 
115      """ 
116   
117      # Format the text. 
118      file.write("\n" * prespace) 
119      box(file=file, text=text, char="~") 
120      file.write("\n" * postspace) 
121   
122   
123 -def subtitle(file=None, text=None, prespace=1, postspace=1): 
124      """Format and write out a subtitle to the given file. 
125   
126      @keyword file:      The file object to write to. 
127      @type file:         file object 
128      @keyword text:      The subtitle text. 
129      @type text:         str 
130      @keyword prespace:  The number of empty lines prior to the text printout. 
131      @type prespace:     int 
132      @keyword postspace: The number of empty lines after the text printout. 
133      @type postspace:    int 
134      """ 
135   
136      # Format the text. 
137      file.write("\n" * prespace) 
138      box(file=file, text=text, char="-") 
139      file.write("\n" * postspace) 
140   
141   
142 -def title(file=None, text=None, prespace=2, postspace=1): 
143      """Format and write out a title to the given file. 
144   
145      @keyword file:      The file object to write to. 
146      @type file:         file object 
147      @keyword text:      The title text. 
148      @type text:         str 
149      @keyword prespace:  The number of empty lines prior to the text printout. 
150      @type prespace:     int 
151      @keyword postspace: The number of empty lines after the text printout. 
152      @type postspace:    int 
153      """ 
154   
155      # Format the text. 
156      file.write("\n" * prespace) 
157      box(file=file, text=text, char="=") 
158      file.write("\n" * postspace) 
159   
160   
161 -def underline(file=None, text=None, char=None): 
162      """Format and write out the text underlined by the given character. 
163   
164      @keyword file:      The file object to write to. 
165      @type file:         file object 
166      @keyword text:      The text to underline. 
167      @type text:         str 
168      @keyword char:      The single character to use for the underline. 
169      @type char:         str 
170      """ 
171   
172      # The length and horizontal underline text. 
173      length = len(text) 
174      hline = char * length 
175   
176      # The text. 
177      file.write("%s\n" % text) 
178      file.write("%s\n" % hline) 
179