docutils/parsers/rst/directives/__init__.py

   1 # $Id$
   2 # Author: David Goodger <goodger@python.org>
   3 # Copyright: This module has been placed in the public domain.
   4
   5 """
   6 This package contains directive implementation modules.
   7 """
   8
   9 __docformat__ = 'reStructuredText'
  10
  11 import re
  12 import codecs
  13 import sys
  14
  15 from docutils import nodes
  16 from docutils.parsers.rst.languages import en as _fallback_language_module
  17 if sys.version_info < (2,5):
  18     from docutils._compat import __import__
  19
  20
  21 _directive_registry = {
  22       'attention': ('admonitions', 'Attention'),
  23       'caution': ('admonitions', 'Caution'),
  24       'code': ('body', 'CodeBlock'),
  25       'danger': ('admonitions', 'Danger'),
  26       'error': ('admonitions', 'Error'),
  27       'important': ('admonitions', 'Important'),
  28       'note': ('admonitions', 'Note'),
  29       'tip': ('admonitions', 'Tip'),
  30       'hint': ('admonitions', 'Hint'),
  31       'warning': ('admonitions', 'Warning'),
  32       'admonition': ('admonitions', 'Admonition'),
  33       'sidebar': ('body', 'Sidebar'),
  34       'topic': ('body', 'Topic'),
  35       'line-block': ('body', 'LineBlock'),
  36       'parsed-literal': ('body', 'ParsedLiteral'),
  37       'math': ('body', 'MathBlock'),
  38       'rubric': ('body', 'Rubric'),
  39       'epigraph': ('body', 'Epigraph'),
  40       'highlights': ('body', 'Highlights'),
  41       'pull-quote': ('body', 'PullQuote'),
  42       'compound': ('body', 'Compound'),
  43       'container': ('body', 'Container'),
  44       #'questions': ('body', 'question_list'),
  45       'table': ('tables', 'RSTTable'),
  46       'csv-table': ('tables', 'CSVTable'),
  47       'list-table': ('tables', 'ListTable'),
  48       'image': ('images', 'Image'),
  49       'figure': ('images', 'Figure'),
  50       'contents': ('parts', 'Contents'),
  51       'sectnum': ('parts', 'Sectnum'),
  52       'header': ('parts', 'Header'),
  53       'footer': ('parts', 'Footer'),
  54       #'footnotes': ('parts', 'footnotes'),
  55       #'citations': ('parts', 'citations'),
  56       'target-notes': ('references', 'TargetNotes'),
  57       'meta': ('html', 'Meta'),
  58       #'imagemap': ('html', 'imagemap'),
  59       'raw': ('misc', 'Raw'),
  60       'include': ('misc', 'Include'),
  61       'replace': ('misc', 'Replace'),
  62       'unicode': ('misc', 'Unicode'),
  63       'class': ('misc', 'Class'),
  64       'role': ('misc', 'Role'),
  65       'default-role': ('misc', 'DefaultRole'),
  66       'title': ('misc', 'Title'),
  67       'date': ('misc', 'Date'),
  68       'restructuredtext-test-directive': ('misc', 'TestDirective'),}
  69 """Mapping of directive name to (module name, class name).  The
  70 directive name is canonical & must be lowercase.  Language-dependent
  71 names are defined in the ``language`` subpackage."""
  72
  73 _directives = {}
  74 """Cache of imported directives."""
  75
  76 def directive(directive_name, language_module, document):
  77     """
  78     Locate and return a directive function from its language-dependent name.
  79     If not found in the current language, check English.  Return None if the
  80     named directive cannot be found.
  81     """
  82     normname = directive_name.lower()
  83     messages = []
  84     msg_text = []
  85     if normname in _directives:
  86         return _directives[normname], messages
  87     canonicalname = None
  88     try:
  89         canonicalname = language_module.directives[normname]
  90     except AttributeError, error:
  91         msg_text.append('Problem retrieving directive entry from language '
  92                         'module %r: %s.' % (language_module, error))
  93     except KeyError:
  94         msg_text.append('No directive entry for "%s" in module "%s".'
  95                         % (directive_name, language_module.__name__))
  96     if not canonicalname:
  97         try:
  98             canonicalname = _fallback_language_module.directives[normname]
  99             msg_text.append('Using English fallback for directive "%s".'
 100                             % directive_name)
 101         except KeyError:
 102             msg_text.append('Trying "%s" as canonical directive name.'
 103                             % directive_name)
 104             # The canonical name should be an English name, but just in case:
 105             canonicalname = normname
 106     if msg_text:
 107         message = document.reporter.info(
 108             '\n'.join(msg_text), line=document.current_line)
 109         messages.append(message)
 110     try:
 111         modulename, classname = _directive_registry[canonicalname]
 112     except KeyError:
 113         # Error handling done by caller.
 114         return None, messages
 115     try:
 116         module = __import__(modulename, globals(), locals(), level=1)
 117     except ImportError, detail:
 118         messages.append(document.reporter.error(
 119             'Error importing directive module "%s" (directive "%s"):\n%s'
 120             % (modulename, directive_name, detail),
 121             line=document.current_line))
 122         return None, messages
 123     try:
 124         directive = getattr(module, classname)
 125         _directives[normname] = directive
 126     except AttributeError:
 127         messages.append(document.reporter.error(
 128             'No directive class "%s" in module "%s" (directive "%s").'
 129             % (classname, modulename, directive_name),
 130             line=document.current_line))
 131         return None, messages
 132     return directive, messages
 133
 134 def register_directive(name, directive):
 135     """
 136     Register a nonstandard application-defined directive function.
 137     Language lookups are not needed for such functions.
 138     """
 139     _directives[name] = directive
 140
 141 def flag(argument):
 142     """
 143     Check for a valid flag option (no argument) and return ``None``.
 144     (Directive option conversion function.)
 145
 146     Raise ``ValueError`` if an argument is found.
 147     """
 148     if argument and argument.strip():
 149         raise ValueError('no argument is allowed; "%s" supplied' % argument)
 150     else:
 151         return None
 152
 153 def unchanged_required(argument):
 154     """
 155     Return the argument text, unchanged.
 156     (Directive option conversion function.)
 157
 158     Raise ``ValueError`` if no argument is found.
 159     """
 160     if argument is None:
 161         raise ValueError('argument required but none supplied')
 162     else:
 163         return argument  # unchanged!
 164
 165 def unchanged(argument):
 166     """
 167     Return the argument text, unchanged.
 168     (Directive option conversion function.)
 169
 170     No argument implies empty string ("").
 171     """
 172     if argument is None:
 173         return u''
 174     else:
 175         return argument  # unchanged!
 176
 177 def path(argument):
 178     """
 179     Return the path argument unwrapped (with newlines removed).
 180     (Directive option conversion function.)
 181
 182     Raise ``ValueError`` if no argument is found.
 183     """
 184     if argument is None:
 185         raise ValueError('argument required but none supplied')
 186     else:
 187         path = ''.join([s.strip() for s in argument.splitlines()])
 188         return path
 189
 190 def uri(argument):
 191     """
 192     Return the URI argument with whitespace removed.
 193     (Directive option conversion function.)
 194
 195     Raise ``ValueError`` if no argument is found.
 196     """
 197     if argument is None:
 198         raise ValueError('argument required but none supplied')
 199     else:
 200         uri = ''.join(argument.split())
 201         return uri
 202
 203 def nonnegative_int(argument):
 204     """
 205     Check for a nonnegative integer argument; raise ``ValueError`` if not.
 206     (Directive option conversion function.)
 207     """
 208     value = int(argument)
 209     if value < 0:
 210         raise ValueError('negative value; must be positive or zero')
 211     return value
 212
 213 def percentage(argument):
 214     """
 215     Check for an integer percentage value with optional percent sign.
 216     """
 217     try:
 218         argument = argument.rstrip(' %')
 219     except AttributeError:
 220         pass
 221     return nonnegative_int(argument)
 222
 223 length_units = ['em', 'ex', 'px', 'in', 'cm', 'mm', 'pt', 'pc']
 224
 225 def get_measure(argument, units):
 226     """
 227     Check for a positive argument of one of the units and return a
 228     normalized string of the form "<value><unit>" (without space in
 229     between).
 230
 231     To be called from directive option conversion functions.
 232     """
 233     match = re.match(r'^([0-9.]+) *(%s)$' % '|'.join(units), argument)
 234     try:
 235         float(match.group(1))
 236     except (AttributeError, ValueError):
 237         raise ValueError(
 238             'not a positive measure of one of the following units:\n%s'
 239             % ' '.join(['"%s"' % i for i in units]))
 240     return match.group(1) + match.group(2)
 241
 242 def length_or_unitless(argument):
 243     return get_measure(argument, length_units + [''])
 244
 245 def length_or_percentage_or_unitless(argument, default=''):
 246     """
 247     Return normalized string of a length or percentage unit.
 248
 249     Add <default> if there is no unit. Raise ValueError if the argument is not
 250     a positive measure of one of the valid CSS units (or without unit).
 251
 252     >>> length_or_percentage_or_unitless('3 pt')
 253     '3pt'
 254     >>> length_or_percentage_or_unitless('3%', 'em')
 255     '3%'
 256     >>> length_or_percentage_or_unitless('3')
 257     '3'
 258     >>> length_or_percentage_or_unitless('3', 'px')
 259     '3px'
 260     """
 261     try:
 262         return get_measure(argument, length_units + ['%'])
 263     except ValueError:
 264         try:
 265             return get_measure(argument, ['']) + default
 266         except ValueError:
 267             # raise ValueError with list of valid units:
 268             return get_measure(argument, length_units + ['%'])
 269
 270 def class_option(argument):
 271     """
 272     Convert the argument into a list of ID-compatible strings and return it.
 273     (Directive option conversion function.)
 274
 275     Raise ``ValueError`` if no argument is found.
 276     """
 277     if argument is None:
 278         raise ValueError('argument required but none supplied')
 279     names = argument.split()
 280     class_names = []
 281     for name in names:
 282         class_name = nodes.make_id(name)
 283         if not class_name:
 284             raise ValueError('cannot make "%s" into a class name' % name)
 285         class_names.append(class_name)
 286     return class_names
 287
 288 unicode_pattern = re.compile(
 289     r'(?:0x|x|\\x|U\+?|\\u)([0-9a-f]+)$|&#x([0-9a-f]+);$', re.IGNORECASE)
 290
 291 def unicode_code(code):
 292     r"""
 293     Convert a Unicode character code to a Unicode character.
 294     (Directive option conversion function.)
 295
 296     Codes may be decimal numbers, hexadecimal numbers (prefixed by ``0x``,
 297     ``x``, ``\x``, ``U+``, ``u``, or ``\u``; e.g. ``U+262E``), or XML-style
 298     numeric character entities (e.g. ``&#x262E;``).  Other text remains as-is.
 299
 300     Raise ValueError for illegal Unicode code values.
 301     """
 302     try:
 303         if code.isdigit():                  # decimal number
 304             return unichr(int(code))
 305         else:
 306             match = unicode_pattern.match(code)
 307             if match:                       # hex number
 308                 value = match.group(1) or match.group(2)
 309                 return unichr(int(value, 16))
 310             else:                           # other text
 311                 return code
 312     except OverflowError, detail:
 313         raise ValueError('code too large (%s)' % detail)
 314
 315 def single_char_or_unicode(argument):
 316     """
 317     A single character is returned as-is.  Unicode characters codes are
 318     converted as in `unicode_code`.  (Directive option conversion function.)
 319     """
 320     char = unicode_code(argument)
 321     if len(char) > 1:
 322         raise ValueError('%r invalid; must be a single character or '
 323                          'a Unicode code' % char)
 324     return char
 325
 326 def single_char_or_whitespace_or_unicode(argument):
 327     """
 328     As with `single_char_or_unicode`, but "tab" and "space" are also supported.
 329     (Directive option conversion function.)
 330     """
 331     if argument == 'tab':
 332         char = '\t'
 333     elif argument == 'space':
 334         char = ' '
 335     else:
 336         char = single_char_or_unicode(argument)
 337     return char
 338
 339 def positive_int(argument):
 340     """
 341     Converts the argument into an integer.  Raises ValueError for negative,
 342     zero, or non-integer values.  (Directive option conversion function.)
 343     """
 344     value = int(argument)
 345     if value < 1:
 346         raise ValueError('negative or zero value; must be positive')
 347     return value
 348
 349 def positive_int_list(argument):
 350     """
 351     Converts a space- or comma-separated list of values into a Python list
 352     of integers.
 353     (Directive option conversion function.)
 354
 355     Raises ValueError for non-positive-integer values.
 356     """
 357     if ',' in argument:
 358         entries = argument.split(',')
 359     else:
 360         entries = argument.split()
 361     return [positive_int(entry) for entry in entries]
 362
 363 def encoding(argument):
 364     """
 365     Verfies the encoding argument by lookup.
 366     (Directive option conversion function.)
 367
 368     Raises ValueError for unknown encodings.
 369     """
 370     try:
 371         codecs.lookup(argument)
 372     except LookupError:
 373         raise ValueError('unknown encoding: "%s"' % argument)
 374     return argument
 375
 376 def choice(argument, values):
 377     """
 378     Directive option utility function, supplied to enable options whose
 379     argument must be a member of a finite set of possible values (must be
 380     lower case).  A custom conversion function must be written to use it.  For
 381     example::
 382
 383         from docutils.parsers.rst import directives
 384
 385         def yesno(argument):
 386             return directives.choice(argument, ('yes', 'no'))
 387
 388     Raise ``ValueError`` if no argument is found or if the argument's value is
 389     not valid (not an entry in the supplied list).
 390     """
 391     try:
 392         value = argument.lower().strip()
 393     except AttributeError:
 394         raise ValueError('must supply an argument; choose from %s'
 395                          % format_values(values))
 396     if value in values:
 397         return value
 398     else:
 399         raise ValueError('"%s" unknown; choose from %s'
 400                          % (argument, format_values(values)))
 401
 402 def format_values(values):
 403     return '%s, or "%s"' % (', '.join(['"%s"' % s for s in values[:-1]]),
 404                             values[-1])
 405
 406 def value_or(values, other):
 407     """
 408     The argument can be any of `values` or `argument_type`.
 409     """
 410     def auto_or_other(argument):
 411         if argument in values:
 412             return argument
 413         else:
 414             return other(argument)
 415     return auto_or_other
 416