3 @setfilename ../../info/srecode
4 @set TITLE SRecoder Manual
5 @set AUTHOR Eric M. Ludlam
6 @settitle @value{TITLE}
8 @c Merge all indexes into a single index for now.
9 @c We can always separate them later into two or more as needed.
18 Copyright @copyright{} 2007-2012 Free Software Foundation, Inc.
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.3 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
25 and with the Back-Cover Texts as in (a) below. A copy of the license
26 is included in the section entitled ``GNU Free Documentation License''.
28 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
29 modify this GNU manual. Buying copies from the FSF supports it in
30 developing GNU and promoting software freedom.''
34 @dircategory Emacs misc features
36 * SRecode: (srecode). Template code generator.
41 @center @titlefont{SRecode}
42 @vskip 0pt plus 1 fill
43 @center by @value{AUTHOR}
61 @srecode{} is the @i{Semantic Recoder}. Where @semantic{} will parse
62 source files into lists of tags, the @i{Semantic Recoder} will aid in
63 converting @semantic{} tags and various other information back into
64 various types of code.
66 While the @srecode{} tool provides a template language, templates for
67 several languages, and even a sequence of heuristics that aid the user
68 in choosing a template to insert, this is not the main goal of
71 The goal of @srecode{} is to provide an application framework where
72 someone can write a complex code generator, and the underlying
73 template commonality allows it to work in multiple languages with
81 * Quick Start:: Basic Setup for template insertion.
82 * User Templates:: Custom User Templates
83 * Parts of SRecode:: Parts of the system
84 * SRecode Minor Mode:: A minor mode for using templates
85 * Template Writing:: How to write a template
86 * Dictionaries:: How dictionaries work
87 * Developing Template Functions:: How to write your own template insert functions.
88 * Template Naming Conventions:: Creating a set of core templates
89 * Inserting Tag Lists:: Inserting Semantic tags via templates
90 * Application Writing:: Writing an @srecode{}r application
91 * GNU Free Documentation License:: The license for this documentation.
99 When you install CEDET and enable @srecode{}, an @code{SRecoder} menu
102 To toggle @srecode{} minor mode on and off use:
105 M-x srecode-minor-mode RET
109 M-x global-srecode-minor-mode RET
115 (srecode-minor-mode 1)
118 into a language hook function to force it on (which is the default) or
119 pass in @code{-1} to force it off.
121 See @ref{SRecode Minor Mode} for more on using the minor mode.
123 Use the menu to insert templates into the current file.
125 You can add your own templates in @file{~/.srecode}, or update the
128 @deffn Option srecode-map-load-path
129 @anchor{srecode-map-load-path}
130 Global load path for SRecode template files.
134 Once installed, you can start inserting templates using the menu, or
137 @deffn Command srecode-insert template-name &rest dict-entries
138 @anchor{srecode-insert}
139 Insert the template @var{template-name} into the current buffer at point.
140 @var{dict-entries} are additional dictionary values to add.
143 SRecode Insert will prompt for a template name. Template names are
144 specific to each major mode. A typical name is of the form:
145 @code{CONTEXT:NAME} where a @var{CONTEXT} might be something like
146 @code{file} or @code{declaration}. The same @var{NAME} can occur in
150 @chapter User Templates
152 @srecode{} builds and maintains a map of all template files. The root
153 template files resides in the @srecode{} distribution. User written
154 templates files are saved in @file{~/.srecode}, along with the
157 @defvar srecode-map-save-file
158 @anchor{srecode-map-save-file}
159 The save location for SRecode's map file.
162 Template files end with a @file{.srt} extension. Details on how to
163 write templates are in @ref{Template Writing}.
165 Each template file you write is dedicated to a single major mode. In
166 it, you can write templates within the same context and with the same
167 name as core templates. You can force your templates to override the
168 core templates for a particular major mode by setting the
169 priority. See @ref{Special Variables}.
171 To get going quickly, open a new @file{.srt} file. It will start in
172 the @srecode{} template writing mode. Use the @srecode{} minor mode
173 menu to insert the @code{empty} file template.
175 When using templates in other modes (such as C++ or Emacs Lisp
176 templates), use the ``Edit Template'' menu to find a template you
177 would like to update. Copy it into your user template file, and
180 If you were to update @code{declaration:function} in your user
181 template file, then you would get this new template instead of the one
182 that comes with @srecode{}. Higher level applications should always
183 use @code{declaration:function} when generating their own code, so
184 higher level templates will then adopt your changes to
185 @code{declaration:function} into themselves.
187 You can also override variables. Core variables are stored in the
188 @srecode{} root template file @file{default.srt}, and that contains
189 the copyright usually used, and some basic file setup formats.
190 Override variables like this by specifying a @code{mode} of
191 @code{default} like this:
197 @node Parts of SRecode
198 @chapter Parts of SRecode
200 The @srecode{} system is made up of several layers which work together
203 @section Template Layer
204 The template layer provides a way to write, and compile templates. The
205 template layer is the scheme used to insert text into an Emacs buffer.
207 The @srecode{} template layer is more advanced than other modes like the
208 Emacs packages @code{skeleton} or @code{tempo} in that it allows
209 multiple layers of templates to be created with the same names. This
210 means that @srecode{} can provide a wide range of templates, and users
211 can override only the small sections they want, instead of either
212 accepting someone else's template, or writing large new templates of
215 Templates are written in @file{.srt} files. You can learn how to
216 author new @file{.srt} files @ref{Template Writing}.
218 While the template system was designed for @srecode{} based
219 applications it can also be used independently for simple template
220 insertion during typical coding.
222 @section Template Manager
223 Once templates have been written, a scheme for loading and selecting
224 templates is needed. The template manager has a loader for finding
225 template files, and determining which templates are relevant to the
226 current buffer. Template files are sorted by priority, with user
227 templates being found first, and system level default templates last.
228 Templates are also sorted by application. Each application has its
229 own templates, and are kept seperate from the generic templates.
232 Dictionaries contain values associated with variable. Variables are
233 used in macros in a template. Variables are what allows a generic
234 template such as a function to be made specific, such as a function
235 named foo. The value of a variable can be one of three things; a
236 string, a list of more dictionaries, or a special
237 @code{srecode-dictionary-compound-value} object subclass. See
238 @ref{Variables} for more.
240 @section Template Insertion
241 The template insertion layer involves extensions to the basic template
242 layer. A wide range of custom variables are available for mixing derived
243 data as macros into the plain text of a template.
245 In addition, templates can be declared with arguments. These
246 arguments represent predetermined sets of dictionary values, such as
247 features of the current file name, user name, time, etc.
249 Some arguments are major-mode specific, such as the @code{:el} or
250 @code{:cpp} arguments.
253 @section Template Insertion Context
254 A context can be provided for templates in a file. This helps
255 auto-selection of templates by name, or allows templates in different
256 contexts to have the same name. Some standard contexts are
257 @code{file}, @code{declaration}, and @code{classdecl}.
259 A context can be automatically derived as well based on the parsing
260 state from @i{Semantic}. @inforef{Top, Semantic Manual, semantic}.
263 @section Applications
264 Commands that do a particular user task which involves also writing
265 Emacs Lisp code. Applications are at the top layer. These
266 applications have their own template files and logic needed to fill in
267 dictionaries or position a cursor. SRecode comes with an example
268 @code{srecode-document} application for creating comments for Semantic
269 tags. The CEDET application @i{EDE} has a project type that is an
270 @srecode{} application.
272 @section Field Editing
273 If the variable @code{srecode-insert-ask-variable-method} is set to
274 'field, then variables that would normally ask a question, will
275 instead create ``fields'' in the buffer. A field-editing layer
276 provides simple interaction through the fields. Typing in a field
277 will cause all variable locations that are the same to edit at the
278 same time. Pressing TAB on a field will move you to the next field.
280 @node SRecode Minor Mode
281 @chapter SRecode Minor Mode
283 The Semantic Recode minor mode enables a keymap and menu that provides
284 simple access to different templates or template applications.
286 The key prefix is @key{C-c /}.
288 If the variable @code{srecode-takeover-INS-key} is set, then the key
289 @key{<insert>} can also be used.
291 The most important key is bound to @code{srecode-insert} which is
292 @key{C-c / /}, or @key{insert insert}. @ref{Quick Start}.
294 Major keybindings are:
298 Insert a template whose name is typed into the minibuffer.
299 @item C-c / <lower case letter>
300 Reserved for direct binding of simple templates to keys using a
301 keybinding command in the template file.
302 @item C-c / <upper case letter>
303 Reserved for template applications (Such as comment or get/set inserter.)
305 Edit the code of a template.
307 Insert template again. This will cause the previously inserted
308 template to be inserted again.
311 @section Field Editing
313 By default, when inserting a template, if the user needs to enter text
314 to fill in a part of the template, then the minibuffer is used to
315 query for that information. SRecode also supports a field-edting mode
316 that can be used instead. To enable it set:
318 @defun srecode-insert-ask-variable-method
319 @anchor{srecode-insert-ask-variable-method}
320 Determine how to ask for a dictionary value when inserting a template.
321 Only the @var{ASK} style inserter will query the user for a value.
322 Dictionary value references that ask begin with the ? character.
326 Prompt in the minibuffer as the value is inserted.
328 Use the dictionary macro name as the inserted value,
329 and place a field there. Matched fields change together.
332 @b{NOTE}: The field feature does not yet work with XEmacs.
335 Field editing mode is supported in newer versions of Emacs. You
336 will not be prompted to fill in values while the template is
337 inserted. Instead, short regions will be highlighted, and the cursor
338 placed in a field. Typing in the field will then fill in the value.
339 Several fields might be linked together. In that case, typing in one
340 area will modify the other linked areas. Pressing TAB will move
341 between editable fields in the template.
343 Once the cursor moves out of the are inserted by the template, all the
344 fields are cancelled.
346 @b{NOTE}: Some conveniences in templates, such as completion, or
347 character restrictins are lost when using field editing mode.
349 @node Template Writing
350 @chapter Template Writing
351 @anchor{@code{SRecode-template-mode}}
353 @code{srecode-template-mode} is the major mode used for designing new
354 templates. @srecode{} files (Extension @file{.srt}) are made up of
355 variable settings and template declarations.
357 Here is an overview of the terminology you will need for the next few
362 A file with a @file{.srt} extension which contains settings,
363 variables, and templates.
365 One named entity which represents a block of text that will be
366 inserted. The text is compiled into a sequence of insertable
367 entities. The entities are string constants, and macros.
369 A macro is a text sequence within template text that is replaced with
372 A table of variable names and values.
374 A dictionary that is subordinate under another dictionary as a value
377 A variable is an entry in a dictionary which has a value.
381 * Variables:: Creating special and regular variables.
382 * Templates:: Creating templates
383 * Contexts:: Templates are grouped by context
384 * Prompts:: Setting prompts for interactive insert macros
390 Variables can be set up and used in templates. Many variables you may
391 use are set up via template arguments, but some may be preferences a
392 user can set up that are used in system templates.
394 When expanding a template, variables are stored in a @dfn{dictionary}.
395 Dictionary entries are variables. Variables defined in templates can
396 have string like values.
398 A variable can be set like this:
400 set VARNAME "some value"
403 Note that a VARIABLE is a name in a dictionary that can be used in a
404 MACRO in a template. The macro referernces some variable by name.
407 * String Values:: Basic Variable values
408 * Multi-string Values:: Complex variable values
409 * Section Show:: Enabling the display of a named section.
410 * Special Variables:: Variables with special names
411 * Automatic Loop Variables:: Variables automatically set in section loops.
412 * Compound Variable Values:: Compound Variable Values
416 @subsection String Values
418 Variables can be set to strings. Strings may contain newlines or any
419 other characters. Strings are interpreted by the Emacs Lisp reader so
420 @code{\n}, @code{\t}, and @code{\"} work.
422 When a string is inserted as part of a template, nothing within the
423 string is interperted, such as template escape characters.
425 @node Multi-string Values
426 @subsection Multi-string Values
428 A variable can be set to multiple strings. A compound value is
429 usually used when you want to use dictionary entries as part of a
432 Multi-string variable values are set like string values except there
433 are more than one. For example
436 set NAME "this" "-mode"
439 These two strings will be concatenated together.
441 A more useful thing is to include dictionary variables and concatenate
442 those into the string. Use the ``macro'' keyword to include the name
443 of a variable. This is like macros in a template. For example:
446 set NAME macro "MODE" "-mode"
449 will extract the value of the dictionary variable MODE and append
450 ``-mode'' to the end.
453 @subsection Section Show
455 To set a variable to show a template section, use the @code{show}
456 command. Sections are blocks of a template wrapped in section macros.
457 If there is a section macro using @var{NAME} it will be shown for each
458 dictionary associated with the @var{NAME} macro.
464 This will enable that section.
467 NOTE: May 11, 2008 - I haven't used this yet, so I don't know if it works.
470 @node Special Variables
471 @subsection Special Variables
473 Some variables have special meaning that changes attributes when
474 templates are compiled, including:
478 This is the character sequence that escapes from raw text to template
479 macro names. The ability to change the escape characters are key for
480 enabling @srecode{} templates to work across many kinds of languages.
482 This is the character sequence that escapes the end of a template
491 This is the major mode, as a string with the full Emacs Lisp symbol in
492 it. All templates in this file will be installed into the template
493 table for this major mode.
495 Multiple template files can use the same mode, and all those templates
496 will be available in buffers of that mode.
500 set mode "emacs-lisp-mode"
504 The priority of a file is a number in a string constant that
505 indicates where it lies in the template search order. System
506 templates default to low priority numbers. User templates default to
507 high priority numbers. You can specify the priority of your template
508 to insert it anywhere in the template search list.
510 If there are multiple templates with the same context and name, the
511 template with the highest priority number will be used.
513 If multiple files have the same priority, then then sort order is
514 unpredictable. If no template names match, then it doesn't matter.
522 If a template file contains templates only needed for a particular
523 application, then specify an application. Template files for an
524 application are stored in the template repository, but are not used in
525 the generic template insertion case.
527 The application with a particular name will access these templates
532 set application "document"
536 If a template file contains templates, or template overrides specific
537 to a set of files under a particular directory, then that template
538 file can specify a ``project'' that it belongs to.
540 Set the ``project'' special variable to a directory name. Only files
541 under that directory will be able to access the templates in that
544 Any template file that has a project specified will get have a
545 priority that is set between SRecode base templates, and user defined
548 Templates can be compiled via a project system, such as EDE. EDE
549 loaded templates will get a @var{project} set automatically.
553 set project "/tmp/testproject"
558 If you need to insert the characters that belong to the variables
559 @code{escape_start} or @code{escape_end}, then place those into
560 a variable. For example
568 @node Automatic Loop Variables
569 @subsection Automatic Loop Variables
571 When section macros are used, that section is repeated for each
572 subdictionary bound to the loop variable.
574 Each dictionary added will automatically get values for positional
575 macros which will enable different @var{sections}. The automatic
576 section variables are.
579 @item @var{first} - The first entry in the table.
580 @item @var{notfirst} - Not the first entry in the table.
581 @item @var{last} - The last entry in the table
582 @item @var{notlast} - Not the last entry in the table.
585 @node Compound Variable Values
586 @subsection Compound Variable Values
588 A variable can also have a compound value. This means the value of
589 the variable is an @EIEIO{} object, which is a subclass of
590 @code{srecode-dictionary-compound-value}.
592 New compound variables can only be setup from Lisp code. See
593 @ref{Compound Dictionary Values} for details on setting up compound
599 A template represents a text pattern that can be inserted into
602 A basic template is declaired like this:
605 template TEMPLATENAME :arg1 :arg2
606 "Optional documentation string"
608 The text to your template goes here.
613 Templates are stored in a template table by name, and are inserted by
614 the @var{templatename} provided.
616 The documentation string is optional. This documentation string will
617 be used to aid users in selecting which template they want to use.
619 The code that makes up the raw template occurs between the lines that
620 contain the text "-----".
623 * Template Section Dictionaries:: Template Scoped Macro values
624 * Template Macros:: Macros occuring in template patterns
627 @node Template Section Dictionaries
628 @subsection Template Section Dictionaries
630 To add variable values to section dictionaries used within a specific
631 template, you can add them to the beginning of the template
632 declaration like this:
635 template TEMPLATENAME :arg1 :arg2
636 "Optional documentation string"
637 sectiondictionary "A"
640 A beginning line @{@{NAME@}@}
641 @{@{#A@}@}Optional string @{@{NAME@}@} here@{@{/A@}@}
646 In this example, the @var{NAME} variable gets the value ``foo'', but
647 only while it is inside section macro A. The outer scoped NAME will
650 This is particularly useful while using an include macro to pull in a
651 second template. In this way, you can pass values known from one
652 template to a subordinate template where some value is not known.
654 From the Emacs Lisp default template file, a syntax table is just a
655 variable with a specialized value.
657 If a variable is declared like this (where $ is the escape character):
660 template variable :el
669 then you can see that there is a NAME and DOC that is needed.
670 The @code{^} point inserter is also a handy key here.
672 The syntax table wants a variable, but knows the values of some of
673 these variables, and can recast the problem like this by using
674 template specific @code{sectiondictionary} macro declarations.
677 template syntax-table
678 "Create a syntax table."
679 sectiondictionary "A"
680 set NAME macro "?MODESYM" "-mode-syntax-table"
681 set DOC "Syntax table used in " macro "?MODESYM" " buffers."
684 (let ((table (make-syntax-table (standard-syntax-table))))
685 (modify-syntax-entry ?\; ". 12" table) ;; SEMI, Comment start ;;
692 In this way, @var{NAME} can be set as a user posed question for
693 @var{MODESYM} with ``-mode-syntax-table'' appended. A simplified doc
694 string will also be inserted.
696 Lastly, the @var{A} section contains more macro text which is inserted
697 at the @code{^} point marker.
699 By creating useful base templates for things like function or variable
700 declarations, and recycling them in higher-order templates, an end
701 user can override the basic declarator, and the higher order templates
702 will then obey the new format, or perhaps even work in more than one
705 @node Template Macros
706 @subsection Template Macros
708 Template macros occur in the template text. The default escape
709 characters are ``@{@{`` and ``@}@}'', though they can be changed
710 in the top-level variables. See @ref{Variables}.
712 Thus, if you have the template code that looks like this:
715 ;; Author: @{@{AUTHOR@}@}
718 Then the text between @{@{ and @}@} are a macro, and substituted by
719 the value of the variable @var{AUTHOR}.
721 Macros can be specialized to be more than just a text string. For
722 example, the macro above could be augmented with an Emacs Lisp
726 ;; Author: @{@{AUTHOR:upcase@}@}
729 In this case, the Emacs Lisp function @code{upcase} will be called on
730 the text value of the @var{AUTHOR} variable.
732 Macros can also be specialized to have different behaviors by using a
733 prefix, non-alpha character or symbol. For example:
736 @{@{! This is a comment inside macro escape characters @}@}
739 shows that the ``!'' symbol is for comments.
741 Alternately, a macro could query the user during insertion:
744 (defun @{@{?NAME@}@} ()
746 ) ;; End of @{@{NAME@}@}
749 the ``?'' symbol indicates that if the symbol @var{NAME} isn't in the
750 dictionary, then the user should be queried for the @var{NAME}
751 variable. If @var{NAME} appears again in the template, the original
752 value specified by the user will be inserted again.
754 If the text from a dictionary value is to be placed in column format,
755 you can use the ``|'' symbol to indicate you want column control. For
759 | this | that |@{@{#A@}@}
760 | @{@{|THIS:4@}@} | @{@{|THAT:4@}@} |@{@{/A@}@}
763 For each repeated section ``#A'' the dictionary values for @var{THIS}
764 and @var{THAT} will be inserted and either trimmed to, or expanded to
765 4 characters in width.
767 Macros that are prefixed with the ``#'' symbol denote a section. A
768 macro of the same name with a ``/'' prefix denotes the end of that
773 Here is some text describing moose.
777 In this example if the section MOOSE was ``shown'' in the active
778 dictionary, then the text between the # and / macros will also be
781 All the text and macros within a section are either not shown at all
782 (if that section is not 'visible') or the section is shown one time
783 for each dictionary added to that symbol.
784 @xref{Developing Template Functions}.
787 Macros prefixed with ``>'' will include another template. Include
788 macros would look like this:
794 where @code{FOO} is the dictionary variable for the sub-dictionary used for
795 expanding the template @code{defun}. The @code{defun} template will
796 be looked up in the template repository for the current mode, or in
799 Another way to include another template is with an include macro that
800 will also wrap section text. The includewrap insertion method looks
804 @{@{<FOO:defun@}@}Handy Text goes here@{@{/FOO@}@}
807 In this case, @code{defun} is included just as above. If the
808 @code{defun} template has a @{@{^@}@} macro in it, then the
809 section text ``Handy Text goes here'' will be inserted at that point,
810 and that location will not be saved as the cursor location.
812 If there is no @{@{^@}@}, then the text will not be inserted.
814 For both kinds of include macros, you may need to include a template
815 from a different context. You can use @code{:} separate the context
816 from the name, like this:
819 @{@{>FOO:declaration:function@}@}
825 Each template belongs to a context. When promting for a template by
826 name, such as with @kbd{C-c / /}, the name is prefixed by the current
827 context. If there is no context, it defaults to @code{declaration}.
829 You can change context like this:
835 where @var{name} is some symbol that represents any context.
837 A context resides over all templates that come after it until the next
838 context statement. Thus:
856 creates two @code{foo} templates. The first one is when in context
857 C1. The second is available in context C2.
859 This is useful if there are multiple ways to declare something like a
860 function or variable that differ only by where it is in the syntax of
861 the lanugage. The name @code{foo} is not ambiguous because each is in
867 Some templates use promtping macro insertion. A macro that needs a
868 prompt looks like this:
874 where ? comes after the first escape character.
876 by default, it will use a prompt like this when it is encountered:
882 For such macros, you can pre-define prompts for any dictionary entry.
883 When that dictionary entry is first encountered, the user is prompted,
884 and subsequent occurances of that dictionary entry use the same value.
886 To get a different prompt, use a prompt command like this:
889 prompt VARNAME "Nice Way to ask for VARNAME: "
892 Now, if you put this in a template:
897 (defvar @{@{?VARNAME@}@} nil
902 when VARNAME is encountered, it will use the nice prompt.
904 Prompts can be extended as well. For example:
907 prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p
910 In this case, the @code{default} keyword indicates that
911 @code{"srecode"} is the default string to use, and @code{y-or-n-p} is
912 the function to use to ask the question.
914 For @code{y-or-n-p} if you type ``y'' it inserts the default string,
915 otherwise it inserts empty.
917 For any other symbol that occurs after the @code{read} token, it is
918 expected to take the same argument list as @code{read-string}. As
919 such, you can create your own prompts that do completing reads on
920 deterministic values.
922 To have the default be calculated later from a dictionary entry, you
923 need to use the @code{defaultmacro} keyword instead.
926 prompt VARNAME "Varname: " defaultmacro "PREFIX"
929 now, when it attempts to read in VARNAME, it will pre-populte the text
930 editing section with whatever the value of PREFIX is.
932 Some language arguments may supply possible prefixes for prompts.
933 Look for these when creating your prompts.
936 @chapter Dictionaries
938 Dictionaries are a set of variables. The values associated with the
939 variable names could be anything, but how it is handled is dependent
940 on the type of macro being inserted.
942 Most of this chapter is for writing Lisp programs that use @srecode{}.
943 If you only want to write template files, then you only need to read
944 the @ref{Template Argument Dictionary Entries} section.
947 * Create a Dictionary::
948 * Setting Dictionary Values:: Basic dictionary values
949 * Compound Dictionary Values:: Complex dictionary values
950 * Argument Resolution:: Automatic template argument resolution
951 * Creating new Arguments:: Create new arguments for use in templates
952 * Querying a Dictionary:: Querying a dictionary for values.
953 * Template Argument Dictionary Entries:: Catalog of arguments
956 @node Create a Dictionary
957 @section Create a Dictionary
959 @defun srecode-create-dictionary &optional buffer
960 @anchor{srecode-create-dictionary}
961 Create a dictionary for @var{buffer}.
962 If @var{buffer} is not specified, use the current buffer.
963 The dictionary is initialized with no variables or enabled sections.
964 Any variables defined with @code{set} in the template, however,
965 becomes a name in the dictionary.
968 @node Setting Dictionary Values
969 @section Setting Dictionary Values
971 When building an @srecode{} based application, you will need to setup
972 your dictionary values yourself. There are several utility functions
975 In the simplest form, you can assocate a string with a variable.
977 @defun srecode-dictionary-set-value dict name value
978 @anchor{srecode-dictionary-set-value}
979 In dictionary @var{dict}, set @var{name} to have @var{value}.
982 For section macros, you can have alternate values. A section can
983 either be toggled as visible, or it can act as a loop.
985 @defun srecode-dictionary-show-section dict name
986 @anchor{srecode-dictionary-show-section}
987 In dictionary @var{dict}, indicate that the section @var{name} should be exposed.
991 @defun srecode-dictionary-add-section-dictionary dict name show-only
992 @anchor{srecode-dictionary-add-section-dictionary}
993 In dictionary @var{DICT}, add a section dictionary for section macro @var{NAME}.
994 Return the new dictionary.
996 You can add several dictionaries to the same section entry.
997 For each dictionary added to a variable, the block of codes in
998 the template will be repeated.
1000 If optional argument @var{SHOW-ONLY} is non-@code{nil}, then don't add a new dictionarly
1001 if there is already one in place. Also, don't add @var{FIRST}/@var{LAST} entries.
1002 These entries are not needed when we are just showing a section.
1004 Each dictionary added will automatically get values for positional macros
1005 which will enable @var{SECTIONS} to be enabled.
1009 The first entry in the table.
1011 Not the first entry in the table.
1013 The last entry in the table
1015 Not the last entry in the table.
1018 Adding a new dictionary will alter these values in previously
1019 inserted dictionaries.
1022 @node Compound Dictionary Values
1023 @section Compound Dictionary Values
1025 If you want to associate a non-string value with a dictionary
1026 variable, then you will need to use a compound value. Compound
1027 dictionary values are derived using @EIEIO{} from a base class for
1028 handling arbitrary data in a macro.
1030 @deffn Type srecode-dictionary-compound-value
1031 @anchor{srecode-dictionary-compound-value}
1032 A compound dictionary value.
1033 Values stored in a dictionary must be a @var{string},
1034 a dictionary for showing sections, or an instance of a subclass
1037 Compound dictionary values derive from this class, and must
1038 provide a sequence of method implementations to convert into
1042 Your new subclass of the compound value needs to implement these
1045 @defun srecode-compound-toString cp function dictionary
1046 @anchor{srecode-compound-toString}
1047 Convert the compound dictionary value @var{cp} to a string.
1048 If @var{function} is non-@code{nil}, then @var{function} is somehow applied to an aspect
1049 of the compound value. The @var{function} could be a fraction
1050 of some function symbol with a logical prefix excluded.
1053 The next method is for dumping out tables during debugging.
1055 @defun srecode-dump cp &optional indent
1056 @anchor{srecode-dump}
1057 Display information about this compound value.
1061 Here is an example of wrapping a semantic tag in a compound value:
1064 (defclass srecode-semantic-tag (srecode-dictionary-compound-value)
1065 ((prime :initarg :prime
1068 "This is the primary insertion tag.")
1070 "Wrap up a collection of semantic tag information.
1071 This class will be used to derive dictionary values.")
1073 (defmethod srecode-compound-toString((cp srecode-semantic-tag)
1076 "Convert the compound dictionary value CP to a string.
1077 If FUNCTION is non-nil, then FUNCTION is somehow applied to an
1078 aspect of the compound value."
1080 ;; Just format it in some handy dandy way.
1081 (semantic-format-tag-prototype (oref cp :prime))
1082 ;; Otherwise, apply the function to the tag itself.
1083 (funcall function (oref cp :prime))
1087 @node Argument Resolution
1088 @section Argument Resolution
1090 Some dictionary entries can be set via template arguments in the
1091 template declaration. For examples of template arguments, see
1092 @ref{Template Argument Dictionary Entries}.
1094 You can resolve an argument list into a dictionary with:
1096 @defun srecode-resolve-arguments temp dict
1097 @anchor{srecode-resolve-arguments}
1098 Resolve all the arguments needed by the template @var{temp}.
1099 Apply anything learned to the dictionary @var{dict}.
1102 @node Creating new Arguments
1103 @section Creating new Arguments
1105 You can create new arguments for use in template files by writing new
1106 Emacs Lisp functions. Doing so is easy. Here is an example for the
1107 @code{:user} argument:
1110 (defun srecode-semantic-handle-:user (dict)
1111 "Add macros into the dictionary DICT based on the current :user."
1112 (srecode-dictionary-set-value dict "AUTHOR" (user-full-name))
1113 (srecode-dictionary-set-value dict "LOGIN" (user-login-name))
1118 In this case, a function with the name prefix
1119 @code{srecode-semantic-handle-} that ends in @code{:user} creates a
1120 new argument @code{:user} that can be used in a template.
1122 Your argument handler must take one argument @var{dict}, which is the
1123 dictionary to fill in. Inside your function, you can do whatever you
1124 want, but adding dictionary values is the right thing.
1126 @node Querying a Dictionary
1127 @section Querying a Dictionary
1129 When creating a new argument, it may be useful to ask the dicitonary
1130 what entries are already set there, and conditionally create new
1131 entries based on those.
1133 In this way, a template author can get additional logic through more
1136 @defun srecode-dictionary-lookup-name dict name
1137 @anchor{srecode-dictionary-lookup-name}
1138 Return information about the current @var{DICT}'s value for @var{NAME}.
1139 @var{DICT} is a dictionary, and @var{NAME} is a string that is the name of
1140 a symbol in the dictionary.
1141 This function derives values for some special NAMEs, such as @var{FIRST}
1147 @node Template Argument Dictionary Entries
1148 @section Template Argument Dictionary Entries
1150 When a dictionary is initialized for a template, then the dictionary
1151 will be initialized with a predefined set of macro values.
1153 A template of the form:
1156 template template-name :arg1 :arg2
1158 Your template goes here
1162 specifies two arguments :arg1, and :arg2.
1164 The following built-in simple arguments are available:
1168 * Semantic Arguments::
1169 * Language Arguments::
1172 @node Base Arguments
1173 @subsection Base Arguments
1175 @subsubsection Argument :indent
1177 Supplies the @code{INDENT} macro. When @code{INDENT} is non-nil, then
1178 each line is individually indented with
1179 @code{indent-according-to-mode} during macro processing.
1181 @subsubsection Argument :blank
1183 Specifying this argument adds a special @code{:blank} handler at the
1184 beginning and end of the template. This handler will insert @code{\n}
1185 if the insertion point is not on a line by itself.
1187 @subsubsection Argument :region
1189 If there is an active region via @code{transient-mark-mode}, or
1190 @code{mouse-drag-region}, then the @code{REGION} section will be
1193 In addition, @code{REGIONTEXT} will be set the the text in the region,
1194 and that region of text will be ``killed'' from the current buffer.
1196 If standard-output is NOT the current buffer, then the region will not
1197 be deleted. In this way, you can safely use @code{:region} using
1198 templates in arbitrary output streams.
1200 @subsubsection Argument :user
1202 Sets up variables about the current user.
1206 Value of the Emacs function @code{user-full-name}
1208 Current Emacs user's email address.
1210 Current Emacs user's login name.
1212 Current Emacs user's login ID.
1214 This Emacs sessions' init file.
1217 @subsubsection Argument :time
1219 Sets up variables with the current date and time.
1225 The current month as a number.
1227 The current month name, unabbreviated.
1229 The current day as a number.
1231 The current day of the week as an abbreviated name
1233 The current hour in 24 hour format.
1235 The current hour in 12 hour format.
1237 Locale equivalent of AM or PM. Usefule with HOUR12.
1243 The timezone string.
1245 The Locale supported date (%D).
1247 The Locale supported time format (%X).
1250 @subsubsection Argument :file
1252 Sets up variables with details about the current file.
1256 The filename without the directory part of the current buffer.
1258 The filename without the directory or extension
1260 The filename extension.
1262 The directory in which the current buffer resides.
1264 Major mode of this buffer.
1266 Major mode of this buffer without ``-mode''.
1267 Useful for inserting the Emacs mode specifier.
1269 Show the section RCS if there is a CVS or RCS directory here.
1272 @subsubsection Argument :system
1274 Sets up variables with computer system information.
1278 The ``system-configuration''.
1280 The ``system-type''.
1282 The ``system-name''.
1284 The name of the machine Emacs derived mail ``comes from''.
1287 @subsubsection Argument :kill
1291 The top-most item from the kill ring.
1293 The second item in the kill ring.
1295 The third item in the kill ring.
1297 The fourth item in the kill ring.
1300 @node Semantic Arguments
1301 @subsection Semantic Arguments
1303 @subsubsection Argument :tag
1305 The :tag argument is filled in with information from Semantic.
1306 The tag in question is queried from the senator tag ring, or passed
1307 in from @srecode{} utilities that use tags in templates.
1311 This is a compound value for the tag in the current senator kill ring,
1312 or something handled via the variable
1313 @code{srecode-semantic-selected-tag}.
1315 @defvar srecode-semantic-selected-tag
1316 @anchor{srecode-semantic-selected-tag}
1317 The tag selected by a @code{:tag} template argument.
1318 If this is @code{nil}, then @code{senator-tag-ring} is used.
1321 Use the function part of a macro insert to extract obscure parts
1324 The name of the tag as a string.
1326 The data type of the tag as a string.
1329 If @var{tag} is a function, you will get these additional dictionary
1334 A Loop macro value. Each argument is inserted in ARGS. To create a
1335 comma separated list of arguments, you might do this:
1338 @{@{#ARGS@}@}@{@{TYPE@}@} @{@{NAME@}@}@{@{#NOTLAST@}@},@{@{/NOTLAST@}@}@{@{/ARGS@}@}
1341 Within the section dictionaries for each argument, you will find both
1342 @var{NAME} and @var{TYPE}, in addition to the automatic section values
1343 for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}.
1345 The string name of the parent of this function, if the function is a
1346 method of some class.
1348 In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified.
1351 If @var{tag} is a variable, you will get these dictionary entries.
1355 Enabled if there is a @var{VALUE}.
1357 An entry in the @var{HAVEDEFAULT} subdictionary that represents the
1358 textual representation of the default value of this variable.
1361 If @var{tag} is a datatype, you will get these dictionary entries.
1365 Section dictionaries for the parents of this class. Each parent will
1368 Section dictionaries for all the implemented interfaces of this
1369 class. Each interface will have a @var{NAME}.
1372 Note that data type templates should always have a @code{@{@{^@}@}}
1373 macro in it where the core contents of that type will go. This is why
1374 data types don't have subdictionaries full of the slots in the classes
1377 @node Language Arguments
1378 @subsection language Arguments
1380 Each language typically has its own argument. These arguments can be
1381 used to fill in language specific values that will be useful.
1383 @subsubsection Argument :srt
1385 Used for SRecoder template files.
1389 The characters used for an escape start
1391 The characters used for an escape end
1394 @subsubsection Argument :cpp
1398 Shows this section if the current file is a header file.
1400 The opposite of @code{HEADER}.
1401 @item FILENAME_SYMBOL
1402 The current filename reformatted as a C friendly symbol.
1405 @subsection Argument :java
1408 @item FILENAME_AS_PACKAGE
1409 Converts the filename into text that would be suitable as a package
1411 @item FILENAME_AS_CLASS
1412 Converts the filename into text that would be suitable as a class-name
1413 for the main class in the file.
1414 @item CURRENT_PACKAGE
1415 Finds the occurance of ``package'' and gets its value.
1418 @subsubsection Argument :el
1420 Sets @code{PRENAME}. This would be a common prefix from all the
1421 tags in the current buffer.
1423 Most Emacs Lisp packages have some common prefix used in a way similar
1424 to namespaces in other languages.
1426 @subsubsection Argument :el-custom
1430 The name of the Emacs Custom group that instances of @code{defcustom}
1433 The name of the Emacs Custom group that faces delcared with
1434 @code{defface} ought to use.
1437 @subsubsection Argument :texi
1441 The current section level, such as @code{chapter} or @code{section}.
1443 The next level down, so if @code{LEVEL} is @code{chapter}, then
1444 @code{NEXTLEVEL} would be @code{section}.
1447 @subsubsection Argument :texitag
1449 The @code{:texitag} argument is like the @code{:tag} argument, except that
1450 additional variable @code{TAGDOC} is provided for each tag.
1452 The @code{TAGDOC} is filled with derived documentation from the tag in
1453 question, and that documentation is also reformatted to be mostly
1456 @subsection Argument :android
1458 The @code{:android} argument pulls in information from your current
1461 @@TODO - add more here.
1463 @node Developing Template Functions
1464 @chapter Developing Template Functions
1466 You can develop your own custom template insertion functions.
1467 Doing so is relatively simple, and requires that you write an Emacs
1470 If the built in commands don't provide enough options, you will need
1471 to write your own function in order to provide your dictionaries with
1472 the values needed for custom templates.
1474 In this way, you can build your own code generator for any language
1475 based on a set of predefined macros whos values you need to derive
1476 from Emacs Lisp code yourself.
1481 (defun my-srecode-insert (template-name)
1482 "Insert the template TEMPLATE-NAME into the current buffer at point."
1484 ;; Read in a template name.
1485 (interactive (list (srecode-read-template-name "Template Name: ")))
1486 (if (not (srecode-table))
1487 (error "No template table found for mode %s" major-mode))
1488 (let ((temp (srecode-template-get-table (srecode-table) template-name))
1490 ;; Create a new dictionary
1491 (newdict (srecode-create-dictionary)))
1494 (error "No Template named %s" template-name))
1496 ;; Add some values into the dictionary!
1497 (srecode-dictionary-set-value newdict "FOO" (my-get-value-of-foo))
1498 ;; Optionally show a section
1499 (srecode-dictionary-show-section newdict "BLARG")
1501 ;; Add in several items over a loop
1502 (let ((my-stuff (get-my-stuff-list)))
1504 (let ((subdict (srecode-dictionary-add-section-dictionary
1506 (srecode-dictionary-set-value subdict "NAME" (nth 0 my-stuff))
1507 (srecode-dictionary-set-value subdict "ARG" (nth 1 my-stuff))
1508 (srecode-dictionary-set-value subdict "MOOSE" (nth 2 my-stuff))
1510 (setq my-stuff (cdr my-stuff)))
1512 ;; Some templates have arguments that need to be resolved.
1513 (srecode-resolve-arguments temp newdict)
1516 (srecode-insert-fcn temp newdict)
1520 Lets look at the key functions involved above:
1522 @section Interactive Completion:
1524 @defun srecode-read-template-name prompt
1525 @anchor{srecode-read-template-name}
1526 Completing read for Semantic Recoder template names.
1527 @var{prompt} is used to query for the name of the template desired.
1530 @section Template Lookup
1532 Even if your program does not query the user for a template name, you
1533 will need to locate a template. First, you need to locate the table
1534 to look the template up in.
1536 @defun srecode-table &optional mode
1537 @anchor{srecode-table}
1538 Return the currently active Semantic Recoder table for this buffer.
1539 Optional argument @var{MODE} specifies the mode table to use.
1543 @defun srecode-template-get-table tab template-name &optional context application
1544 @anchor{srecode-template-get-table}
1545 Find in the template in mode table @var{TAB}, the template with @var{TEMPLATE-NAME}.
1546 Optional argument @var{CONTEXT} specifies a context a particular template
1548 Optional argument @var{APPLICATION} restricts searches to only template tables
1549 belonging to a specific application. If @var{APPLICATION} is @code{nil}, then only
1550 tables that do not belong to an application will be searched.
1553 For purposes of an @srecode{} application, it is important to decide
1554 what to call yoru application, and use that with this method call.
1556 @section Creating dictionaries
1558 Several dictionary calls are made in this example, including:
1560 @item srecode-create-dictionary
1561 @item srecode-dictionary-set-value
1562 @item srecode-dictionary-show-section
1563 @item srecode-dictionary-add-section-dictionary
1566 These are documented more fully @ref{Dictionaries}.
1568 Also used is @code{srecode-resolve-arguments}. To learn more about
1569 that, see @ref{Argument Resolution}.
1571 @section Template Insertion Commands
1573 There are several ways to insert a template. It is easiest to just
1574 start with the main entry point.
1576 @defun srecode-insert-fcn template dictionary &optional stream
1577 @anchor{srecode-insert-fcn}
1578 Insert @var{template} using @var{dictionary} into @var{stream}.
1579 If @var{stream} is nil, then use the current buffer.
1582 @node Template Naming Conventions
1583 @chapter Template Naming Conventions
1585 For @srecode{} to work across langauges reliably, templates need to
1586 follow a predictable pattern. For every language of similar nature
1587 (OO, functional, doc based) if they all provide the same base
1588 templates, then an application can be written against the base
1589 templates, and it will work in each of the supported language.
1591 Having consistent templates also makes it easy to use those templates
1592 from a user perspective during basic interactive insertion via
1593 @code{srecode-minor-mode}.
1596 NOTES ON THIS CHAPTER:
1598 These conventions are being worked on. Check w/ CEDET-DEVEL mailing
1599 list if you want to support a language, or write an application and
1600 provide your opinions on this topic. Any help is appreciated.
1603 @section Context: File
1605 Each language should support the @code{file:empty} template. This
1606 will generally use the default copyright insertion mechanism.
1608 @section Context: Declaration
1610 Functional languages should attempt to support the following:
1614 A standalone function. Not a method, external method, or other.
1616 A method belonging to some class declaired outside the textual bounds
1617 of that class' declaration.
1621 A data type. If the language supports several types of datatypes
1622 then do not use this, use more specific ones instead.
1624 For OO languages, use this instead of @code{type}.
1629 For any @semantic{} tag class in your language, you will likely want
1630 to have a corresponding template.
1632 In order for the @srecode{} function
1633 @code{srecode-semantic-insert-tag} to work, you can create templates
1634 similar to those mentioned above, except with @code{-tag} appended to
1635 the end. This lets a template like @code{function} have user
1636 conveniences when referencing @code{function-tag}, while also
1637 allowing the tag inserter to do its job with a simpler template.
1639 @section Context: Classdef
1641 Inside a class definition. These are to be inserted inside the
1642 textual bounds of a class declaration.
1646 This would be a method of the class being inserted into.
1649 Like @code{function} but specific to alloc/delete of an object.
1651 This would be a field of the class being inserted into.
1654 @section Context: Code
1656 Inside a body of code, such as a function or method body.
1658 - no conventions yet.
1660 @section Standard Dictionary Values
1662 For these variables to be useful, standard names should be used.
1663 These values could be provided directly from a Semantic tag, or by an
1668 The name of the declaration being created.
1670 If the item belongs to some parent type, it would be the full name of
1671 that type, including namespaces.
1673 A datatype name for a variable, or the return value of a function.
1675 If there is some documentation associated with the item, then DOC
1676 should contain the value. (Optional)
1678 The ARGS variable defines a section for 0 or more arguments to a function
1679 or method. Each entry in ARGS will follow the rest of these naming
1680 conventions, such as for NAME and TYPE.
1683 For templates used by @code{srecode-semantic-insert-tag}, there is
1684 also the following useful dictionary values.
1688 A special insertion value TAG. You can use semantic functions to turn
1689 the tag into a string.
1692 Default value for a variable.
1695 @node Inserting Tag Lists
1696 @chapter Inserting Tag Lists
1698 Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for
1699 @srecode{} is to convert lists of tags, as produced by @semantic{}
1702 A single function provides the interface for programs to do this, but
1703 it requires any particular language to have provided the correct
1704 templates to make it work.
1706 @defun srecode-semantic-insert-tag tag &optional style-option point-insert-fcn &rest dict-entries
1707 @anchor{srecode-semantic-insert-tag}
1708 Insert @var{tag} into a buffer using srecode templates at point.
1710 Optional @var{style-option} is a list of minor configuration of styles,
1711 such as the symbol @code{'prototype} for prototype functions, or
1712 @code{'system} for system includes, and @code{'doxygen}, for a doxygen style
1715 Optional third argument @var{point-insert-fcn} is a hook that is run after
1716 @var{tag} is inserted that allows an opportunity to fill in the body of
1717 some thing. This hook function is called with one argument, the @var{tag}
1720 The rest of the arguments are @var{dict-entries}. @var{dict-entries}
1721 is of the form ( @var{name1} @var{value1} @var{name2} @var{value2} @dots{} NAMEn VALUEn).
1723 The exact template used is based on the current context.
1724 The template used is found within the toplevel context as calculated
1725 by @dfn{srecode-calculate-context}, such as @code{declaration}, @code{classdecl},
1728 For various conditions, this function looks for a template with
1729 the name @var{class}-tag, where @var{class} is the tag class. If it cannot
1730 find that, it will look for that template in the
1731 @code{declaration}context (if the current context was not @code{declaration}).
1733 If @var{prototype} is specified, it will first look for templates with
1734 the name @var{class}-tag-prototype, or @var{class}-prototype as above.
1736 See @dfn{srecode-semantic-apply-tag-to-dict} for details on what is in
1737 the dictionary when the templates are called.
1739 This function returns to location in the buffer where the
1740 inserted tag @var{ends}, and will leave point inside the inserted
1741 text based on any occurrence of a point-inserter. Templates such
1742 as @dfn{function} will leave point where code might be inserted.
1746 @node Application Writing
1747 @chapter Application Writing
1749 The main goal of @srecode{} is to provide a strong platform for
1750 writing code generating applications.
1752 Any templates that are application specific should make an application
1753 declaration for each template file they use. This prevents those
1754 templates from being used outside of that application.
1756 For example, add this to a file:
1758 set application "getset"
1761 In your application Emacs Lisp code, you would then load those
1762 templates. A typical initialization would look like this:
1765 (srecode-load-tables-for-mode major-mode)
1766 (srecode-load-tables-for-mode major-mode 'getset)
1769 These two lines will load in the base templates for the major mode,
1770 and then the application specific templates.
1772 @defun srecode-load-tables-for-mode mmode &optional appname
1773 @anchor{srecode-load-tables-for-mode}
1774 Load all the template files for @var{mmode}.
1775 Templates are found in the SRecode Template Map.
1776 See @dfn{srecode-get-maps} for more.
1777 @var{appname} is the name of an application. In this case,
1778 all template files for that application will be loaded.
1782 todo - Add examples. Most core stuff is already described above.
1785 @node GNU Free Documentation License
1786 @appendix GNU Free Documentation License
1787 @include doclicense.texi