From: David G. <go...@us...> - 2003-07-09 17:59:41
|
Update of /cvsroot/docutils/docutils/docutils/parsers/rst/directives In directory sc8-pr-cvs1:/tmp/cvs-serv32580/docutils/parsers/rst/directives Modified Files: __init__.py Log Message: Renamed ``unchanged()`` directive option conversion function to ``unchanged_required``, and added a new ``unchanged``. Updated docstrings. Index: __init__.py =================================================================== RCS file: /cvsroot/docutils/docutils/docutils/parsers/rst/directives/__init__.py,v retrieving revision 1.21 retrieving revision 1.22 diff -u -d -r1.21 -r1.22 --- __init__.py 3 Jun 2003 02:16:59 -0000 1.21 +++ __init__.py 9 Jul 2003 17:59:37 -0000 1.22 @@ -60,7 +60,8 @@ - ``options``: A dictionary, mapping known option names to conversion functions such as `int` or `float`. ``None`` or an empty dict implies no - options to parse. + options to parse. Several directive option conversion functions are defined + in this module. - ``content``: A boolean; true if content is allowed. Client code must handle the case where content is required but not supplied (an empty content list @@ -186,6 +187,7 @@ def flag(argument): """ Check for a valid flag option (no argument) and return ``None``. + (Directive option conversion function.) Raise ``ValueError`` if an argument is found. """ @@ -194,9 +196,10 @@ else: return None -def unchanged(argument): +def unchanged_required(argument): """ - Return the argument, unchanged. + Return the argument text, unchanged. + (Directive option conversion function.) Raise ``ValueError`` if no argument is found. """ @@ -205,9 +208,22 @@ else: return argument # unchanged! +def unchanged(argument): + """ + Return the argument text, unchanged. + (Directive option conversion function.) + + No argument implies empty string (""). + """ + if argument is None: + return u'' + else: + return argument # unchanged! + def path(argument): """ Return the path argument unwrapped (with newlines removed). + (Directive option conversion function.) Raise ``ValueError`` if no argument is found or if the path contains internal whitespace. @@ -224,17 +240,44 @@ def nonnegative_int(argument): """ Check for a nonnegative integer argument; raise ``ValueError`` if not. + (Directive option conversion function.) """ value = int(argument) if value < 0: raise ValueError('negative value; must be positive or zero') return value + +def class_option(argument): + """ + Convert the argument into an ID-compatible string and return it. + (Directive option conversion function.) + + Raise ``ValueError`` if no argument is found. + """ + if argument is None: + raise ValueError('argument required but none supplied') + return nodes.make_id(argument) + def format_values(values): return '%s, or "%s"' % (', '.join(['"%s"' % s for s in values[:-1]]), values[-1]) def choice(argument, values): + """ + Directive option utility function, supplied to enable options whose + argument must be a member of a finite set of possible values (must be + lower case). A custom conversion function must be written to use it. For + example:: + + from docutils.parsers.rst import directives + + def yesno(argument): + return directives.choice(argument, ('yes', 'no')) + + Raise ``ValueError`` if no argument is found or if the argument's value is + not valid (not an entry in the supplied list). + """ try: value = argument.lower().strip() except AttributeError: @@ -245,8 +288,3 @@ else: raise ValueError('"%s" unknown; choose from %s' % (argument, format_values(values))) - -def class_option(argument): - if argument is None: - raise ValueError('argument required but none supplied') - return nodes.make_id(argument) |