contribs/pylit_elisp.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3
   4 # ===============================================================
   5 # pylit_elisp.py: Settings and filters for elisp conversion
   6 # ===============================================================
   7 #
   8 # :Date:      $Date: 2007-05-14 14:14:54 +0200$
   9 # :Version:   SVN-Revision $Revision$
  10 # :URL:       $URL$
  11 # :Copyright: 2007 Riccardo Murri
  12 #             Released under the terms of the GNU General Public License
  13 #             (v. 2 or later)
  14 #
  15 # .. sectnum::
  16 # .. contents::
  17
  18 # Frontmatter
  19 # ===========
  20 #
  21 # Changelog
  22 # ---------
  23 #
  24 # :0.2: Complete rewrite, following G. Milde's suggestions.
  25 # :0.3: * Rewrite filter as iterator generators, the filter interface is
  26 #         moved to pylit.py(GM)
  27 #       * require three semicolons (``;;;``) in section header regexp
  28 # ::
  29
  30 """Emacs lisp for the PyLit code<->text converter.
  31
  32 Defaults and filters for elisp (emacs lisp) code
  33 """
  34
  35 __docformat__ = 'restructuredtext'
  36
  37 _version = "0.3"
  38
  39
  40 # Requirements
  41 # ------------
  42 #
  43 # Regular espressions are used in `ELISP filters` to match
  44 # the ELisp sectioning comments::
  45
  46 import re
  47
  48 import pylit
  49
  50 # Emacs Lisp filters
  51 # ==================
  52 #
  53 #
  54 # ::
  55
  56 def elisp_code_preprocessor(data):
  57     """Convert Emacs Lisp comment sectioning markers to reST comments.
  58
  59     The special headers listed at:
  60
  61       http://www.gnu.org/software/emacs/elisp/html_node/Library-Headers.html#Library-Headers
  62
  63     are converted to reST comment lines and prefixed with the comment
  64     line marker (taken from keyword arguments); all other content is
  65     passed through unchanged.
  66
  67     For instance, ELisp code:
  68
  69       ;;; Code:
  70
  71       ;; here begins the real coding
  72       (defun my-elisp-function () ...)
  73
  74     is translated to:
  75
  76       ;; .. |elisp> ;;; Code:
  77
  78       ;; here begins the real coding
  79       (defun my-elisp-function () ...)
  80     """
  81
  82 # Regular expression matching the special ELisp headers::
  83
  84     SECTION_PATTERN = \
  85         re.compile(';;; *(Change *Log|Code|Commentary|Documentation|History):',\
  86                        re.IGNORECASE)
  87
  88 # Prepend ``.. |elisp> `` to matching headers, one line at a time::
  89
  90     for line in data:
  91         if SECTION_PATTERN.match(line):
  92             yield pylit.defaults.comment_strings["elisp"] + '.. |elisp> ' + line
  93         else:
  94             yield line
  95
  96
  97 def elisp_code_postprocessor(data):
  98     """Convert specially-marked reST comments to Emacs Lisp code.
  99
 100     In all lines, the prefix ``.. |elisp> `` (note
 101     the trailing space!) is stripped from the begin of a line.
 102
 103     For instance, the block:
 104
 105       .. |elisp> ;;; Code:
 106       .. |elisp> (some-elisp-incantation)
 107       (another-one)
 108
 109     is translated to:
 110
 111       ;;; Code:
 112       (some-elisp-incantation)
 113       (another-one)
 114     """
 115
 116     # Set the prefix to be stripped
 117     prefix = pylit.defaults.comment_strings["elisp"] + '.. |elisp> '
 118
 119     for line in data:
 120         if line.startswith(prefix):
 121             yield line[len(prefix):]
 122         else:
 123             yield line
 124
 125
 126
 127 # Register elisp
 128 # ==============
 129 #
 130 # Add default values for "elisp" to the `defaults` object from PyLit.
 131 #
 132 # The following code assumes that this plug-in is always evaluated in the
 133 # pylit namespace and after pylit.py
 134 #
 135 # ::
 136
 137 pylit.defaults.languages[".el"] = "elisp"
 138 pylit.defaults.comment_strings["elisp"] = ';; '
 139
 140 # Filters
 141 pylit.defaults.preprocessors["elisp2text"] = elisp_code_preprocessor
 142 pylit.defaults.postprocessors["text2elisp"] = elisp_code_postprocessor
 143