Package XPyTools :: Package codetpl
[hide private]
[frames] | no frames]

Source Code for Package XPyTools.codetpl

  1  #!/usr/bin/env python
 
  2  # -*- coding: utf-8 -*-
 
  3  #--------------------------------------------------------------------
 
  4  # Author: Mazhugin Aleksey
 
  5  # Created: 2007/09/24
 
  6  # ID: $Id: XPyTools.codetpl-pysrc.html 24 2008-12-01 17:51:12Z alex $
 
  7  # URL: $URL: file:///myfiles/svn_/XPyLIB/trunc/doc/html/XPyTools.codetpl-pysrc.html $
 
  8  # Copyright: Copyright (c) 2007, Mazhugin Aleksey
 
  9  # License: BSD
 
 10  #--------------------------------------------------------------------
 
 11  # Package initialisation
 
 12  
 
 13  """
 
 14  Package for enhance writing of source code.
 
 15  
 
 16  B{List of package}:
 
 17  ===================
 
 18  
 
 19      - codetpl - Code templates.
 
 20      - guiCodeTpl - Gui interface for Code Templates.
 
 21      - [boa_pluggins] - Boa constructor plug-ins.
 
 22          - CodeTemplates.plug-in.py - add codetpl to Boa constructor.
 
 23              Plug-in was named same name as original
 
 24              becouse then assign other name then plug-in do not load or
 
 25              no initialize or other bugs is occurs (on my system ... or may be
 
 26              other systems too, i don't know yet).
 
 27          - CodeTemplates.plug-in.py_v0.6.1.original - The original plug-in that was
 
 28              contributed with Boa constructor 0.6.1 beta. 
 
 29  
 
 30  codetpl manual.
 
 31  ===============
 
 32  
 
 33      Provide functionality for code templates uses.
 
 34      
 
 35      All templates saved into directory "./templates".
 
 36      You may save you templates in other dirictory that you like and
 
 37      add they paths into configuration file.
 
 38      
 
 39      Conventions for templates name: I{typ_name.py}, where
 
 40          - I{typ} - template type,
 
 41          - I{name} - template name.
 
 42      By default defined next types:
 
 43          - kwd_*.py - keywords (used inside templates).
 
 44          - tpl_*.py - templates for insert "Code templates".
 
 45          - act_*.py - template actions "Template actions".
 
 46          - new_*.py - templates for "New file".
 
 47          - wzd_*.py - templates for "Wizards".
 
 48          - wtp_*.py - templates, more powerfull then I{tpl}.
 
 49          
 
 50      Function's definition for template  must like: "C{def ???_*(fields):}",
 
 51      where "I{fields}" - dict (for user enter values for fields),
 
 52      "I{???}" - type of template, "I{*}" - name of template.
 
 53      
 
 54      Function's definition for keywords  must like: "C{def kwd_*():}",
 
 55      where "I{*}" - name of keyword.
 
 56      
 
 57      If function preffix is other or absent then this function is not
 
 58      interpreted as template or keyword.
 
 59      
 
 60      
 
 61      Functions must return string or other objet which may be converted
 
 62      to string by operator C{str()}. From returned string will be removed first
 
 63      and last newline characters. vIf returned string is empty then no
 
 64      result applying to source code.
 
 65      
 
 66      Difference between templates and keywords is that keywords function
 
 67      string paste into code as is, other templates interpreted
 
 68      with using next rules.
 
 69      
 
 70      Interpreter rules.
 
 71      ------------------
 
 72              
 
 73          In string you may use follow templates:
 
 74              
 
 75              - @Name@ - Search and replace "Name" from "fields" dict if not find
 
 76                  then search in keywords.
 
 77              - You must define dictionary "fields" into functions arguments
 
 78                  which contains "FieldsName:FieldsValue" items, where:
 
 79                      
 
 80                      - FieldsName - name that you prompt from user.
 
 81                      - FieldsValue - default value or value that user input.
 
 82                      
 
 83              - Fields may be empty dictionary.
 
 84              
 
 85          First time template functions calls to get template for display
 
 86          user preview of you template, and pass empty fields=={}. You may change
 
 87          value of fields to take caller information about fields. If you do not change
 
 88          fields, then for fields value will be assigne it's names.
 
 89          Second time template-function will be called with entered fields
 
 90          dict as argument and you may use fields
 
 91          values that user entered or assigned by default.
 
 92          All fields are case insensitive, then parsing returned template.
 
 93                  
 
 94          String "I{# Your code}" place into position for user input.
 
 95              
 
 96      All template's functions may have next attributes or other:
 
 97           
 
 98           - language - language for which template applicable.
 
 99           - categoty - category.
 
100           - author - author of template.
 
101           
 
102      Attributes must be written precendence function code into comment in
 
103      next style: B{# metainfoname = value}.
 
104      Example::
 
105          
 
106          # language = python
 
107          # category = Python
 
108          # author = Mazhugin Aleksey
 
109      
 
110      Predefined and known by pluggin in C{./boa-pluggins/CodeTemplates.plug-in.py}
 
111      metainfonames is I{language} and I{category}.
 
112          
 
113      For retrive source file path you must use C{codetpl_sourcefile} global
 
114      variable which auto appending into module dictionary.
 
115      
 
116      If error occurs you may rise exception or return error description into
 
117      template string. If you rise exception then exception type and text will be
 
118      writed instead template.
 
119      
 
120      Loads all finded and right files.
 
121      Last templates override previous with same names.
 
122  """ 
123          
 
124  __all__=['codetpl', 'guiCodeTpl'] 
125