3 @setfilename ../../info/srecode.info
4 @set TITLE SRecoder Manual
5 @set AUTHOR Eric M. Ludlam
6 @settitle @value{TITLE}
9 @c Merge all indexes into a single index for now.
10 @c We can always separate them later into two or more as needed.
19 Copyright @copyright{} 2007--2018 Free Software Foundation, Inc.
22 Permission is granted to copy, distribute and/or modify this document
23 under the terms of the GNU Free Documentation License, Version 1.3 or
24 any later version published by the Free Software Foundation; with no
25 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
26 and with the Back-Cover Texts as in (a) below. A copy of the license
27 is included in the section entitled ``GNU Free Documentation License''.
29 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
30 modify this GNU manual.''
34 @dircategory Emacs misc features
36 * SRecode: (srecode). Semantic template code generator.
41 @center @titlefont{SRecode}
42 @vskip 0pt plus 1 fill
43 @center by @value{AUTHOR}
45 @vskip 0pt plus 1filll
64 @srecode{} is the @i{Semantic Recoder}. Where @semantic{} will parse
65 source files into lists of tags, the @i{Semantic Recoder} will aid in
66 converting @semantic{} tags and various other information back into
67 various types of code.
69 While the @srecode{} tool provides a template language, templates for
70 several languages, and even a sequence of heuristics that aid the user
71 in choosing a template to insert, this is not the main goal of
74 The goal of @srecode{} is to provide an application framework where
75 someone can write a complex code generator, and the underlying
76 template commonality allows it to work in multiple languages with
84 * Quick Start:: Basic Setup for template insertion.
85 * User Templates:: Custom User Templates
86 * Parts of SRecode:: Parts of the system
87 * SRecode Minor Mode:: A minor mode for using templates
88 * Template Writing:: How to write a template
89 * Dictionaries:: How dictionaries work
90 * Developing Template Functions:: How to write your own template insert functions.
91 * Template Naming Conventions:: Creating a set of core templates
92 * Inserting Tag Lists:: Inserting Semantic tags via templates
93 * Application Writing:: Writing an @srecode{}r application
94 * GNU Free Documentation License:: The license for this documentation.
102 When you install CEDET and enable @srecode{}, an @code{SRecoder} menu
105 To toggle @srecode{} minor mode on and off use:
108 M-x srecode-minor-mode @key{RET}
112 M-x global-srecode-minor-mode @key{RET}
118 (srecode-minor-mode 1)
121 into a language hook function to force it on (which is the default) or
122 pass in @code{-1} to force it off.
124 See @ref{SRecode Minor Mode} for more on using the minor mode.
126 Use the menu to insert templates into the current file.
128 You can add your own templates in @file{~/.srecode}, or update the
131 @deffn Option srecode-map-load-path
132 @anchor{srecode-map-load-path}
133 Global load path for SRecode template files.
137 Once installed, you can start inserting templates using the menu, or
140 @deffn Command srecode-insert template-name &rest dict-entries
141 @anchor{srecode-insert}
142 Insert the template @var{template-name} into the current buffer at point.
143 @var{dict-entries} are additional dictionary values to add.
146 SRecode Insert will prompt for a template name. Template names are
147 specific to each major mode. A typical name is of the form:
148 @code{CONTEXT:NAME} where a @var{CONTEXT} might be something like
149 @code{file} or @code{declaration}. The same @var{NAME} can occur in
153 @chapter User Templates
155 @srecode{} builds and maintains a map of all template files. The root
156 template files resides in the @srecode{} distribution. User written
157 templates files are saved in @file{~/.srecode}, along with the
160 @defvar srecode-map-save-file
161 @anchor{srecode-map-save-file}
162 The save location for SRecode's map file.
165 Template files end with a @file{.srt} extension. Details on how to
166 write templates are in @ref{Template Writing}.
168 Each template file you write is dedicated to a single major mode. In
169 it, you can write templates within the same context and with the same
170 name as core templates. You can force your templates to override the
171 core templates for a particular major mode by setting the
172 priority. See @ref{Special Variables}.
174 To get going quickly, open a new @file{.srt} file. It will start in
175 the @srecode{} template writing mode. Use the @srecode{} minor mode
176 menu to insert the @code{empty} file template.
178 When using templates in other modes (such as C++ or Emacs Lisp
179 templates), use the ``Edit Template'' menu to find a template you
180 would like to update. Copy it into your user template file, and
183 If you were to update @code{declaration:function} in your user
184 template file, then you would get this new template instead of the one
185 that comes with @srecode{}. Higher level applications should always
186 use @code{declaration:function} when generating their own code, so
187 higher level templates will then adopt your changes to
188 @code{declaration:function} into themselves.
190 You can also override variables. Core variables are stored in the
191 @srecode{} root template file @file{default.srt}, and that contains
192 the copyright usually used, and some basic file setup formats.
193 Override variables like this by specifying a @code{mode} of
194 @code{default} like this:
200 @node Parts of SRecode
201 @chapter Parts of SRecode
203 The @srecode{} system is made up of several layers which work together
206 @section Template Layer
207 The template layer provides a way to write, and compile templates. The
208 template layer is the scheme used to insert text into an Emacs buffer.
210 The @srecode{} template layer is more advanced than other modes like the
211 Emacs packages @code{skeleton} or @code{tempo} in that it allows
212 multiple layers of templates to be created with the same names. This
213 means that @srecode{} can provide a wide range of templates, and users
214 can override only the small sections they want, instead of either
215 accepting someone else's template, or writing large new templates of
218 Templates are written in @file{.srt} files. You can learn how to
219 author new @file{.srt} files @ref{Template Writing}.
221 While the template system was designed for @srecode{} based
222 applications it can also be used independently for simple template
223 insertion during typical coding.
225 @section Template Manager
226 Once templates have been written, a scheme for loading and selecting
227 templates is needed. The template manager has a loader for finding
228 template files, and determining which templates are relevant to the
229 current buffer. Template files are sorted by priority, with user
230 templates being found first, and system level default templates last.
231 Templates are also sorted by application. Each application has its
232 own templates, and are kept separate from the generic templates.
235 Dictionaries contain values associated with variable. Variables are
236 used in macros in a template. Variables are what allows a generic
237 template such as a function to be made specific, such as a function
238 named foo. The value of a variable can be one of three things; a
239 string, a list of more dictionaries, or a special
240 @code{srecode-dictionary-compound-value} object subclass. See
241 @ref{Variables} for more.
243 @section Template Insertion
244 The template insertion layer involves extensions to the basic template
245 layer. A wide range of custom variables are available for mixing derived
246 data as macros into the plain text of a template.
248 In addition, templates can be declared with arguments. These
249 arguments represent predetermined sets of dictionary values, such as
250 features of the current file name, user name, time, etc.
252 Some arguments are major-mode specific, such as the @code{:el} or
253 @code{:cpp} arguments.
255 @section Template Insertion Context
256 A context can be provided for templates in a file. This helps
257 auto-selection of templates by name, or allows templates in different
258 contexts to have the same name. Some standard contexts are
259 @code{file}, @code{declaration}, and @code{classdecl}.
261 A context can be automatically derived as well based on the parsing
262 state from @i{Semantic}. @inforef{Top, Semantic Manual, semantic}.
264 @section Applications
265 Commands that do a particular user task which involves also writing
266 Emacs Lisp code. Applications are at the top layer. These
267 applications have their own template files and logic needed to fill in
268 dictionaries or position a cursor. SRecode comes with an example
269 @code{srecode-document} application for creating comments for Semantic
270 tags. The CEDET application @i{EDE} has a project type that is an
271 @srecode{} application.
273 @section Field Editing
274 If the variable @code{srecode-insert-ask-variable-method} is set to
275 'field, then variables that would normally ask a question, will
276 instead create ``fields'' in the buffer. A field-editing layer
277 provides simple interaction through the fields. Typing in a field
278 will cause all variable locations that are the same to edit at the
279 same time. Pressing @kbd{@key{TAB}} on a field will move you to the
282 @node SRecode Minor Mode
283 @chapter SRecode Minor Mode
285 The Semantic Recode minor mode enables a keymap and menu that provides
286 simple access to different templates or template applications.
288 The key prefix is @kbd{C-c /}.
290 If the variable @code{srecode-takeover-INS-key} is set, then the key
291 @kbd{@key{INSERT}} can also be used.
293 The most important key is bound to @code{srecode-insert} which is
294 @kbd{C-c / /}, or @kbd{@key{INSERT} @key{INSERT}}. @ref{Quick Start}.
296 Major keybindings are:
300 Insert a template whose name is typed into the minibuffer.
301 @item C-c / <lower case letter>
302 Reserved for direct binding of simple templates to keys using a
303 keybinding command in the template file.
304 @item C-c / <upper case letter>
305 Reserved for template applications (Such as comment or get/set inserter.)
307 Edit the code of a template.
309 Insert template again. This will cause the previously inserted
310 template to be inserted again.
313 @section Field Editing
315 By default, when inserting a template, if the user needs to enter text
316 to fill in a part of the template, then the minibuffer is used to
317 query for that information. SRecode also supports a field-editing mode
318 that can be used instead. To enable it set:
320 @defun srecode-insert-ask-variable-method
321 @anchor{srecode-insert-ask-variable-method}
322 Determine how to ask for a dictionary value when inserting a template.
323 Only the @var{ASK} style inserter will query the user for a value.
324 Dictionary value references that ask begin with the ? character.
328 Prompt in the minibuffer as the value is inserted.
330 Use the dictionary macro name as the inserted value,
331 and place a field there. Matched fields change together.
334 @b{NOTE}: The field feature does not yet work with XEmacs.
337 Field editing mode is supported in newer versions of Emacs. You
338 will not be prompted to fill in values while the template is
339 inserted. Instead, short regions will be highlighted, and the cursor
340 placed in a field. Typing in the field will then fill in the value.
341 Several fields might be linked together. In that case, typing in one
342 area will modify the other linked areas. Pressing @key{TAB} will move
343 between editable fields in the template.
345 Once the cursor moves out of the are inserted by the template, all the
348 @b{NOTE}: Some conveniences in templates, such as completion, or
349 character restrictions are lost when using field editing mode.
351 @node Template Writing
352 @chapter Template Writing
353 @anchor{@code{SRecode-template-mode}}
355 @code{srecode-template-mode} is the major mode used for designing new
356 templates. @srecode{} files (Extension @file{.srt}) are made up of
357 variable settings and template declarations.
359 Here is an overview of the terminology you will need for the next few
364 A file with a @file{.srt} extension which contains settings,
365 variables, and templates.
367 One named entity which represents a block of text that will be
368 inserted. The text is compiled into a sequence of insertable
369 entities. The entities are string constants, and macros.
371 A macro is a text sequence within template text that is replaced with
374 A table of variable names and values.
376 A dictionary that is subordinate under another dictionary as a value
379 A variable is an entry in a dictionary which has a value.
383 * Variables:: Creating special and regular variables.
384 * Templates:: Creating templates
385 * Contexts:: Templates are grouped by context
386 * Prompts:: Setting prompts for interactive insert macros
392 Variables can be set up and used in templates. Many variables you may
393 use are set up via template arguments, but some may be preferences a
394 user can set up that are used in system templates.
396 When expanding a template, variables are stored in a @dfn{dictionary}.
397 Dictionary entries are variables. Variables defined in templates can
398 have string like values.
400 A variable can be set like this:
402 set VARNAME "some value"
405 Note that a VARIABLE is a name in a dictionary that can be used in a
406 MACRO in a template. The macro references some variable by name.
409 * String Values:: Basic Variable values
410 * Multi-string Values:: Complex variable values
411 * Section Show:: Enabling the display of a named section.
412 * Special Variables:: Variables with special names
413 * Automatic Loop Variables:: Variables automatically set in section loops.
414 * Compound Variable Values:: Compound Variable Values
418 @subsection String Values
420 Variables can be set to strings. Strings may contain newlines or any
421 other characters. Strings are interpreted by the Emacs Lisp reader so
422 @code{\n}, @code{\t}, and @code{\"} work.
424 When a string is inserted as part of a template, nothing within the
425 string is interpreted, such as template escape characters.
427 @node Multi-string Values
428 @subsection Multi-string Values
430 A variable can be set to multiple strings. A compound value is
431 usually used when you want to use dictionary entries as part of a
434 Multi-string variable values are set like string values except there
435 are more than one. For example
438 set NAME "this" "-mode"
441 These two strings will be concatenated together.
443 A more useful thing is to include dictionary variables and concatenate
444 those into the string. Use the ``macro'' keyword to include the name
445 of a variable. This is like macros in a template. For example:
448 set NAME macro "MODE" "-mode"
451 will extract the value of the dictionary variable MODE and append
452 ``-mode'' to the end.
455 @subsection Section Show
457 To set a variable to show a template section, use the @code{show}
458 command. Sections are blocks of a template wrapped in section macros.
459 If there is a section macro using @var{NAME} it will be shown for each
460 dictionary associated with the @var{NAME} macro.
466 This will enable that section.
469 NOTE: May 11, 2008: I haven't used this yet, so I don't know if it works.
472 @node Special Variables
473 @subsection Special Variables
475 Some variables have special meaning that changes attributes when
476 templates are compiled, including:
480 This is the character sequence that escapes from raw text to template
481 macro names. The ability to change the escape characters are key for
482 enabling @srecode{} templates to work across many kinds of languages.
484 This is the character sequence that escapes the end of a template
493 This is the major mode, as a string with the full Emacs Lisp symbol in
494 it. All templates in this file will be installed into the template
495 table for this major mode.
497 Multiple template files can use the same mode, and all those templates
498 will be available in buffers of that mode.
502 set mode "emacs-lisp-mode"
506 The priority of a file is a number in a string constant that
507 indicates where it lies in the template search order. System
508 templates default to low priority numbers. User templates default to
509 high priority numbers. You can specify the priority of your template
510 to insert it anywhere in the template search list.
512 If there are multiple templates with the same context and name, the
513 template with the highest priority number will be used.
515 If multiple files have the same priority, then the sort order is
516 unpredictable. If no template names match, then it doesn't matter.
524 If a template file contains templates only needed for a particular
525 application, then specify an application. Template files for an
526 application are stored in the template repository, but are not used in
527 the generic template insertion case.
529 The application with a particular name will access these templates
534 set application "document"
538 If a template file contains templates, or template overrides specific
539 to a set of files under a particular directory, then that template
540 file can specify a ``project'' that it belongs to.
542 Set the ``project'' special variable to a directory name. Only files
543 under that directory will be able to access the templates in that
546 Any template file that has a project specified will get have a
547 priority that is set between SRecode base templates, and user defined
550 Templates can be compiled via a project system, such as EDE@. EDE
551 loaded templates will get a @var{project} set automatically.
555 set project "/tmp/testproject"
560 If you need to insert the characters that belong to the variables
561 @code{escape_start} or @code{escape_end}, then place those into
562 a variable. For example
570 @node Automatic Loop Variables
571 @subsection Automatic Loop Variables
573 When section macros are used, that section is repeated for each
574 subdictionary bound to the loop variable.
576 Each dictionary added will automatically get values for positional
577 macros which will enable different @var{sections}. The automatic
578 section variables are.
581 @item @var{first}---The first entry in the table.
582 @item @var{notfirst}---Not the first entry in the table.
583 @item @var{last}---The last entry in the table
584 @item @var{notlast}---Not the last entry in the table.
587 @node Compound Variable Values
588 @subsection Compound Variable Values
590 A variable can also have a compound value. This means the value of
591 the variable is an @EIEIO{} object, which is a subclass of
592 @code{srecode-dictionary-compound-value}.
594 New compound variables can only be setup from Lisp code. See
595 @ref{Compound Dictionary Values} for details on setting up compound
601 A template represents a text pattern that can be inserted into
604 A basic template is declared like this:
607 template TEMPLATENAME :arg1 :arg2
608 "Optional documentation string"
610 The text to your template goes here.
615 Templates are stored in a template table by name, and are inserted by
616 the @var{templatename} provided.
618 The documentation string is optional. This documentation string will
619 be used to aid users in selecting which template they want to use.
621 The code that makes up the raw template occurs between the lines that
622 contain the text "-----".
625 * Template Section Dictionaries:: Template Scoped Macro values
626 * Template Macros:: Macros occurring in template patterns
629 @node Template Section Dictionaries
630 @subsection Template Section Dictionaries
632 To add variable values to section dictionaries used within a specific
633 template, you can add them to the beginning of the template
634 declaration like this:
637 template TEMPLATENAME :arg1 :arg2
638 "Optional documentation string"
639 sectiondictionary "A"
642 A beginning line @{@{NAME@}@}
643 @{@{#A@}@}Optional string @{@{NAME@}@} here@{@{/A@}@}
648 In this example, the @var{NAME} variable gets the value ``foo'', but
649 only while it is inside section macro A@. The outer scoped NAME will
652 This is particularly useful while using an include macro to pull in a
653 second template. In this way, you can pass values known from one
654 template to a subordinate template where some value is not known.
656 From the Emacs Lisp default template file, a syntax table is just a
657 variable with a specialized value.
659 If a variable is declared like this (where $ is the escape character):
662 template variable :el
671 then you can see that there is a NAME and DOC that is needed.
672 The @code{^} point inserter is also a handy key here.
674 The syntax table wants a variable, but knows the values of some of
675 these variables, and can recast the problem like this by using
676 template specific @code{sectiondictionary} macro declarations.
679 template syntax-table
680 "Create a syntax table."
681 sectiondictionary "A"
682 set NAME macro "?MODESYM" "-mode-syntax-table"
683 set DOC "Syntax table used in " macro "?MODESYM" " buffers."
686 (let ((table (make-syntax-table (standard-syntax-table))))
687 (modify-syntax-entry ?\; ". 12" table) ;; SEMI, Comment start ;;
694 In this way, @var{NAME} can be set as a user posed question for
695 @var{MODESYM} with ``-mode-syntax-table'' appended. A simplified doc
696 string will also be inserted.
698 Lastly, the @var{A} section contains more macro text which is inserted
699 at the @code{^} point marker.
701 By creating useful base templates for things like function or variable
702 declarations, and recycling them in higher-order templates, an end
703 user can override the basic declarator, and the higher order templates
704 will then obey the new format, or perhaps even work in more than one
707 @node Template Macros
708 @subsection Template Macros
710 Template macros occur in the template text. The default escape
711 characters are ``@{@{`` and ``@}@}'', though they can be changed
712 in the top-level variables. See @ref{Variables}.
714 Thus, if you have the template code that looks like this:
717 ;; Author: @{@{AUTHOR@}@}
720 Then the text between @{@{ and @}@} are a macro, and substituted by
721 the value of the variable @var{AUTHOR}.
723 Macros can be specialized to be more than just a text string. For
724 example, the macro above could be augmented with an Emacs Lisp
728 ;; Author: @{@{AUTHOR:upcase@}@}
731 In this case, the Emacs Lisp function @code{upcase} will be called on
732 the text value of the @var{AUTHOR} variable.
734 Macros can also be specialized to have different behaviors by using a
735 prefix, non-alpha character or symbol. For example:
738 @{@{! This is a comment inside macro escape characters @}@}
741 shows that the ``!'' symbol is for comments.
743 Alternately, a macro could query the user during insertion:
746 (defun @{@{?NAME@}@} ()
748 ) ;; End of @{@{NAME@}@}
751 the ``?'' symbol indicates that if the symbol @var{NAME} isn't in the
752 dictionary, then the user should be queried for the @var{NAME}
753 variable. If @var{NAME} appears again in the template, the original
754 value specified by the user will be inserted again.
756 If the text from a dictionary value is to be placed in column format,
757 you can use the ``|'' symbol to indicate you want column control. For
761 | this | that |@{@{#A@}@}
762 | @{@{|THIS:4@}@} | @{@{|THAT:4@}@} |@{@{/A@}@}
765 For each repeated section ``#A'' the dictionary values for @var{THIS}
766 and @var{THAT} will be inserted and either trimmed to, or expanded to
767 4 characters in width.
769 Macros that are prefixed with the ``#'' symbol denote a section. A
770 macro of the same name with a ``/'' prefix denotes the end of that
775 Here is some text describing moose.
779 In this example if the section MOOSE was ``shown'' in the active
780 dictionary, then the text between the # and / macros will also be
783 All the text and macros within a section are either not shown at all
784 (if that section is not 'visible') or the section is shown one time
785 for each dictionary added to that symbol.
786 @xref{Developing Template Functions}.
788 Macros prefixed with ``>'' will include another template. Include
789 macros would look like this:
795 where @code{FOO} is the dictionary variable for the sub-dictionary used for
796 expanding the template @code{defun}. The @code{defun} template will
797 be looked up in the template repository for the current mode, or in
800 Another way to include another template is with an include macro that
801 will also wrap section text. The includewrap insertion method looks
805 @{@{<FOO:defun@}@}Handy Text goes here@{@{/FOO@}@}
808 In this case, @code{defun} is included just as above. If the
809 @code{defun} template has a @{@{^@}@} macro in it, then the
810 section text ``Handy Text goes here'' will be inserted at that point,
811 and that location will not be saved as the cursor location.
813 If there is no @{@{^@}@}, then the text will not be inserted.
815 For both kinds of include macros, you may need to include a template
816 from a different context. You can use @code{:} separate the context
817 from the name, like this:
820 @{@{>FOO:declaration:function@}@}
826 Each template belongs to a context. When prompting for a template by
827 name, such as with @kbd{C-c / /}, the name is prefixed by the current
828 context. If there is no context, it defaults to @code{declaration}.
830 You can change context like this:
836 where @var{name} is some symbol that represents any context.
838 A context resides over all templates that come after it until the next
839 context statement. Thus:
857 creates two @code{foo} templates. The first one is when in context
858 C1. The second is available in context C2.
860 This is useful if there are multiple ways to declare something like a
861 function or variable that differ only by where it is in the syntax of
862 the language. The name @code{foo} is not ambiguous because each is in
868 Some templates use prompting macro insertion. A macro that needs a
869 prompt looks like this:
875 where ? comes after the first escape character.
877 by default, it will use a prompt like this when it is encountered:
883 For such macros, you can pre-define prompts for any dictionary entry.
884 When that dictionary entry is first encountered, the user is prompted,
885 and subsequent occurrences of that dictionary entry use the same value.
887 To get a different prompt, use a prompt command like this:
890 prompt VARNAME "Nice Way to ask for VARNAME: "
893 Now, if you put this in a template:
898 (defvar @{@{?VARNAME@}@} nil
903 when VARNAME is encountered, it will use the nice prompt.
905 Prompts can be extended as well. For example:
908 prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p
911 In this case, the @code{default} keyword indicates that
912 @code{"srecode"} is the default string to use, and @code{y-or-n-p} is
913 the function to use to ask the question.
915 For @code{y-or-n-p} if you type ``y'' it inserts the default string,
916 otherwise it inserts empty.
918 For any other symbol that occurs after the @code{read} token, it is
919 expected to take the same argument list as @code{read-string}. As
920 such, you can create your own prompts that do completing reads on
921 deterministic values.
923 To have the default be calculated later from a dictionary entry, you
924 need to use the @code{defaultmacro} keyword instead.
927 prompt VARNAME "Varname: " defaultmacro "PREFIX"
930 now, when it attempts to read in VARNAME, it will pre-populate the text
931 editing section with whatever the value of PREFIX is.
933 Some language arguments may supply possible prefixes for prompts.
934 Look for these when creating your prompts.
937 @chapter Dictionaries
939 Dictionaries are a set of variables. The values associated with the
940 variable names could be anything, but how it is handled is dependent
941 on the type of macro being inserted.
943 Most of this chapter is for writing Lisp programs that use @srecode{}.
944 If you only want to write template files, then you only need to read
945 the @ref{Template Argument Dictionary Entries} section.
948 * Create a Dictionary::
949 * Setting Dictionary Values:: Basic dictionary values
950 * Compound Dictionary Values:: Complex dictionary values
951 * Argument Resolution:: Automatic template argument resolution
952 * Creating new Arguments:: Create new arguments for use in templates
953 * Querying a Dictionary:: Querying a dictionary for values.
954 * Template Argument Dictionary Entries:: Catalog of arguments
957 @node Create a Dictionary
958 @section Create a Dictionary
960 @defun srecode-create-dictionary &optional buffer
961 @anchor{srecode-create-dictionary}
962 Create a dictionary for @var{buffer}.
963 If @var{buffer} is not specified, use the current buffer.
964 The dictionary is initialized with no variables or enabled sections.
965 Any variables defined with @code{set} in the template, however,
966 becomes a name in the dictionary.
969 @node Setting Dictionary Values
970 @section Setting Dictionary Values
972 When building an @srecode{} based application, you will need to setup
973 your dictionary values yourself. There are several utility functions
976 In the simplest form, you can associate a string with a variable.
978 @defun srecode-dictionary-set-value dict name value
979 @anchor{srecode-dictionary-set-value}
980 In dictionary @var{dict}, set @var{name} to have @var{value}.
983 For section macros, you can have alternate values. A section can
984 either be toggled as visible, or it can act as a loop.
986 @defun srecode-dictionary-show-section dict name
987 @anchor{srecode-dictionary-show-section}
988 In dictionary @var{dict}, indicate that the section @var{name} should be exposed.
992 @defun srecode-dictionary-add-section-dictionary dict name show-only
993 @anchor{srecode-dictionary-add-section-dictionary}
994 In dictionary @var{DICT}, add a section dictionary for section macro @var{NAME}.
995 Return the new dictionary.
997 You can add several dictionaries to the same section entry.
998 For each dictionary added to a variable, the block of codes in
999 the template will be repeated.
1001 If optional argument @var{SHOW-ONLY} is non-@code{nil}, then don't add
1002 a new dictionary if there is already one in place. Also, don't add
1003 @var{FIRST}/@var{LAST} entries.
1004 These entries are not needed when we are just showing a section.
1006 Each dictionary added will automatically get values for positional macros
1007 which will enable @var{SECTIONS} to be enabled.
1011 The first entry in the table.
1013 Not the first entry in the table.
1015 The last entry in the table
1017 Not the last entry in the table.
1020 Adding a new dictionary will alter these values in previously
1021 inserted dictionaries.
1024 @node Compound Dictionary Values
1025 @section Compound Dictionary Values
1027 If you want to associate a non-string value with a dictionary
1028 variable, then you will need to use a compound value. Compound
1029 dictionary values are derived using @EIEIO{} from a base class for
1030 handling arbitrary data in a macro.
1032 @deffn Type srecode-dictionary-compound-value
1033 @anchor{srecode-dictionary-compound-value}
1034 A compound dictionary value.
1035 Values stored in a dictionary must be a @var{string},
1036 a dictionary for showing sections, or an instance of a subclass
1039 Compound dictionary values derive from this class, and must
1040 provide a sequence of method implementations to convert into
1044 Your new subclass of the compound value needs to implement these
1047 @defun srecode-compound-toString cp function dictionary
1048 @anchor{srecode-compound-toString}
1049 Convert the compound dictionary value @var{cp} to a string.
1050 If @var{function} is non-@code{nil}, then @var{function} is somehow applied to an aspect
1051 of the compound value. The @var{function} could be a fraction
1052 of some function symbol with a logical prefix excluded.
1055 The next method is for dumping out tables during debugging.
1057 @defun srecode-dump cp &optional indent
1058 @anchor{srecode-dump}
1059 Display information about this compound value.
1063 Here is an example of wrapping a semantic tag in a compound value:
1066 (defclass srecode-semantic-tag (srecode-dictionary-compound-value)
1067 ((prime :initarg :prime
1070 "This is the primary insertion tag.")
1072 "Wrap up a collection of semantic tag information.
1073 This class will be used to derive dictionary values.")
1075 (defmethod srecode-compound-toString((cp srecode-semantic-tag)
1078 "Convert the compound dictionary value CP to a string.
1079 If FUNCTION is non-nil, then FUNCTION is somehow applied to an
1080 aspect of the compound value."
1082 ;; Just format it in some handy dandy way.
1083 (semantic-format-tag-prototype (oref cp :prime))
1084 ;; Otherwise, apply the function to the tag itself.
1085 (funcall function (oref cp :prime))
1089 @node Argument Resolution
1090 @section Argument Resolution
1092 Some dictionary entries can be set via template arguments in the
1093 template declaration. For examples of template arguments, see
1094 @ref{Template Argument Dictionary Entries}.
1096 You can resolve an argument list into a dictionary with:
1098 @defun srecode-resolve-arguments temp dict
1099 @anchor{srecode-resolve-arguments}
1100 Resolve all the arguments needed by the template @var{temp}.
1101 Apply anything learned to the dictionary @var{dict}.
1104 @node Creating new Arguments
1105 @section Creating new Arguments
1107 You can create new arguments for use in template files by writing new
1108 Emacs Lisp functions. Doing so is easy. Here is an example for the
1109 @code{:user} argument:
1112 (defun srecode-semantic-handle-:user (dict)
1113 "Add macros into the dictionary DICT based on the current :user."
1114 (srecode-dictionary-set-value dict "AUTHOR" (user-full-name))
1115 (srecode-dictionary-set-value dict "LOGIN" (user-login-name))
1120 In this case, a function with the name prefix
1121 @code{srecode-semantic-handle-} that ends in @code{:user} creates a
1122 new argument @code{:user} that can be used in a template.
1124 Your argument handler must take one argument @var{dict}, which is the
1125 dictionary to fill in. Inside your function, you can do whatever you
1126 want, but adding dictionary values is the right thing.
1128 @node Querying a Dictionary
1129 @section Querying a Dictionary
1131 When creating a new argument, it may be useful to ask the dictionary
1132 what entries are already set there, and conditionally create new
1133 entries based on those.
1135 In this way, a template author can get additional logic through more
1138 @defun srecode-dictionary-lookup-name dict name
1139 @anchor{srecode-dictionary-lookup-name}
1140 Return information about the current @var{DICT}'s value for @var{NAME}.
1141 @var{DICT} is a dictionary, and @var{NAME} is a string that is the name of
1142 a symbol in the dictionary.
1143 This function derives values for some special NAMEs, such as @var{FIRST}
1149 @node Template Argument Dictionary Entries
1150 @section Template Argument Dictionary Entries
1152 When a dictionary is initialized for a template, then the dictionary
1153 will be initialized with a predefined set of macro values.
1155 A template of the form:
1158 template template-name :arg1 :arg2
1160 Your template goes here
1164 specifies two arguments :arg1, and :arg2.
1166 The following built-in simple arguments are available:
1170 * Semantic Arguments::
1171 * Language Arguments::
1174 @node Base Arguments
1175 @subsection Base Arguments
1177 @subsubsection Argument :indent
1179 Supplies the @code{INDENT} macro. When @code{INDENT} is non-@code{nil}, then
1180 each line is individually indented with
1181 @code{indent-according-to-mode} during macro processing.
1183 @subsubsection Argument :blank
1185 Specifying this argument adds a special @code{:blank} handler at the
1186 beginning and end of the template. This handler will insert @code{\n}
1187 if the insertion point is not on a line by itself.
1189 @subsubsection Argument :region
1191 If there is an active region via @code{transient-mark-mode}, or
1192 @code{mouse-drag-region}, then the @code{REGION} section will be
1195 In addition, @code{REGIONTEXT} will be set to the text in the region,
1196 and that region of text will be ``killed'' from the current buffer.
1198 If standard-output is NOT the current buffer, then the region will not
1199 be deleted. In this way, you can safely use @code{:region} using
1200 templates in arbitrary output streams.
1202 @subsubsection Argument :user
1204 Sets up variables about the current user.
1208 Value of the Emacs function @code{user-full-name}
1210 Current Emacs user's email address.
1212 Current Emacs user's login name.
1214 Current Emacs user's login ID.
1216 This Emacs sessions' init file.
1219 @subsubsection Argument :time
1221 Sets up variables with the current date and time.
1227 The current month as a number.
1229 The current month name, unabbreviated.
1231 The current day as a number.
1233 The current day of the week as an abbreviated name
1235 The current hour in 24 hour format.
1237 The current hour in 12 hour format.
1239 Locale equivalent of AM or PM@. Useful with HOUR12.
1245 The timezone string.
1247 The Locale supported date (%D).
1249 The Locale supported time format (%X).
1252 @subsubsection Argument :file
1254 Sets up variables with details about the current file.
1258 The filename without the directory part of the current buffer.
1260 The filename without the directory or extension
1262 The filename extension.
1264 The directory in which the current buffer resides.
1266 Major mode of this buffer.
1268 Major mode of this buffer without ``-mode''.
1269 Useful for inserting the Emacs mode specifier.
1271 Show the section RCS if there is a CVS or RCS directory here.
1274 @subsubsection Argument :system
1276 Sets up variables with computer system information.
1280 The ``system-configuration''.
1282 The ``system-type''.
1284 The ``system-name''.
1286 The name of the machine Emacs derived mail ``comes from''.
1289 @subsubsection Argument :kill
1293 The top-most item from the kill ring.
1295 The second item in the kill ring.
1297 The third item in the kill ring.
1299 The fourth item in the kill ring.
1302 @node Semantic Arguments
1303 @subsection Semantic Arguments
1305 @subsubsection Argument :tag
1307 The :tag argument is filled in with information from Semantic.
1308 The tag in question is queried from the senator tag ring, or passed
1309 in from @srecode{} utilities that use tags in templates.
1313 This is a compound value for the tag in the current senator kill ring,
1314 or something handled via the variable
1315 @code{srecode-semantic-selected-tag}.
1317 @defvar srecode-semantic-selected-tag
1318 @anchor{srecode-semantic-selected-tag}
1319 The tag selected by a @code{:tag} template argument.
1320 If this is @code{nil}, then @code{senator-tag-ring} is used.
1323 Use the function part of a macro insert to extract obscure parts
1326 The name of the tag as a string.
1328 The data type of the tag as a string.
1331 If @var{tag} is a function, you will get these additional dictionary
1336 A Loop macro value. Each argument is inserted in ARGS@. To create a
1337 comma separated list of arguments, you might do this:
1340 @{@{#ARGS@}@}@{@{TYPE@}@} @{@{NAME@}@}@{@{#NOTLAST@}@},@{@{/NOTLAST@}@}@{@{/ARGS@}@}
1343 Within the section dictionaries for each argument, you will find both
1344 @var{NAME} and @var{TYPE}, in addition to the automatic section values
1345 for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}.
1347 The string name of the parent of this function, if the function is a
1348 method of some class.
1350 In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified.
1353 If @var{tag} is a variable, you will get these dictionary entries.
1357 Enabled if there is a @var{VALUE}.
1359 An entry in the @var{HAVEDEFAULT} subdictionary that represents the
1360 textual representation of the default value of this variable.
1363 If @var{tag} is a datatype, you will get these dictionary entries.
1367 Section dictionaries for the parents of this class. Each parent will
1370 Section dictionaries for all the implemented interfaces of this
1371 class. Each interface will have a @var{NAME}.
1374 Note that data type templates should always have a @code{@{@{^@}@}}
1375 macro in it where the core contents of that type will go. This is why
1376 data types don't have subdictionaries full of the slots in the classes
1379 @node Language Arguments
1380 @subsection language Arguments
1382 Each language typically has its own argument. These arguments can be
1383 used to fill in language specific values that will be useful.
1385 @subsubsection Argument :srt
1387 Used for SRecoder template files.
1391 The characters used for an escape start
1393 The characters used for an escape end
1396 @subsubsection Argument :cpp
1400 Shows this section if the current file is a header file.
1402 The opposite of @code{HEADER}.
1403 @item FILENAME_SYMBOL
1404 The current filename reformatted as a C friendly symbol.
1407 @subsection Argument :java
1410 @item FILENAME_AS_PACKAGE
1411 Converts the filename into text that would be suitable as a package
1413 @item FILENAME_AS_CLASS
1414 Converts the filename into text that would be suitable as a class-name
1415 for the main class in the file.
1416 @item CURRENT_PACKAGE
1417 Finds the occurrence of ``package'' and gets its value.
1420 @subsubsection Argument :el
1422 Sets @code{PRENAME}. This would be a common prefix from all the
1423 tags in the current buffer.
1425 Most Emacs Lisp packages have some common prefix used in a way similar
1426 to namespaces in other languages.
1428 @subsubsection Argument :el-custom
1432 The name of the Emacs Custom group that instances of @code{defcustom}
1435 The name of the Emacs Custom group that faces declared with
1436 @code{defface} ought to use.
1439 @subsubsection Argument :texi
1443 The current section level, such as @code{chapter} or @code{section}.
1445 The next level down, so if @code{LEVEL} is @code{chapter}, then
1446 @code{NEXTLEVEL} would be @code{section}.
1449 @subsubsection Argument :texitag
1451 The @code{:texitag} argument is like the @code{:tag} argument, except that
1452 additional variable @code{TAGDOC} is provided for each tag.
1454 The @code{TAGDOC} is filled with derived documentation from the tag in
1455 question, and that documentation is also reformatted to be mostly
1458 @subsection Argument :android
1460 The @code{:android} argument pulls in information from your current
1463 @@TODO - add more here.
1465 @node Developing Template Functions
1466 @chapter Developing Template Functions
1468 You can develop your own custom template insertion functions.
1469 Doing so is relatively simple, and requires that you write an Emacs
1472 If the built in commands don't provide enough options, you will need
1473 to write your own function in order to provide your dictionaries with
1474 the values needed for custom templates.
1476 In this way, you can build your own code generator for any language
1477 based on a set of predefined macros whos values you need to derive
1478 from Emacs Lisp code yourself.
1483 (defun my-srecode-insert (template-name)
1484 "Insert the template TEMPLATE-NAME into the current buffer at point."
1486 ;; Read in a template name.
1487 (interactive (list (srecode-read-template-name "Template Name: ")))
1488 (if (not (srecode-table))
1489 (error "No template table found for mode %s" major-mode))
1490 (let ((temp (srecode-template-get-table (srecode-table) template-name))
1492 ;; Create a new dictionary
1493 (newdict (srecode-create-dictionary)))
1496 (error "No Template named %s" template-name))
1498 ;; Add some values into the dictionary!
1499 (srecode-dictionary-set-value newdict "FOO" (my-get-value-of-foo))
1500 ;; Optionally show a section
1501 (srecode-dictionary-show-section newdict "BLARG")
1503 ;; Add in several items over a loop
1504 (let ((my-stuff (get-my-stuff-list)))
1506 (let ((subdict (srecode-dictionary-add-section-dictionary
1508 (srecode-dictionary-set-value subdict "NAME" (nth 0 my-stuff))
1509 (srecode-dictionary-set-value subdict "ARG" (nth 1 my-stuff))
1510 (srecode-dictionary-set-value subdict "MOOSE" (nth 2 my-stuff))
1512 (setq my-stuff (cdr my-stuff)))
1514 ;; Some templates have arguments that need to be resolved.
1515 (srecode-resolve-arguments temp newdict)
1518 (srecode-insert-fcn temp newdict)
1522 Lets look at the key functions involved above:
1524 @section Interactive Completion:
1526 @defun srecode-read-template-name prompt
1527 @anchor{srecode-read-template-name}
1528 Completing read for Semantic Recoder template names.
1529 @var{prompt} is used to query for the name of the template desired.
1532 @section Template Lookup
1534 Even if your program does not query the user for a template name, you
1535 will need to locate a template. First, you need to locate the table
1536 to look the template up in.
1538 @defun srecode-table &optional mode
1539 @anchor{srecode-table}
1540 Return the currently active Semantic Recoder table for this buffer.
1541 Optional argument @var{MODE} specifies the mode table to use.
1545 @defun srecode-template-get-table tab template-name &optional context application
1546 @anchor{srecode-template-get-table}
1547 Find in the template in mode table @var{TAB}, the template with @var{TEMPLATE-NAME}.
1548 Optional argument @var{CONTEXT} specifies a context a particular template
1550 Optional argument @var{APPLICATION} restricts searches to only template tables
1551 belonging to a specific application. If @var{APPLICATION} is @code{nil}, then only
1552 tables that do not belong to an application will be searched.
1555 For purposes of an @srecode{} application, it is important to decide
1556 what to call your application, and use that with this method call.
1558 @section Creating dictionaries
1560 Several dictionary calls are made in this example, including:
1562 @item srecode-create-dictionary
1563 @item srecode-dictionary-set-value
1564 @item srecode-dictionary-show-section
1565 @item srecode-dictionary-add-section-dictionary
1568 These are documented more fully @ref{Dictionaries}.
1570 Also used is @code{srecode-resolve-arguments}. To learn more about
1571 that, see @ref{Argument Resolution}.
1573 @section Template Insertion Commands
1575 There are several ways to insert a template. It is easiest to just
1576 start with the main entry point.
1578 @defun srecode-insert-fcn template dictionary &optional stream
1579 @anchor{srecode-insert-fcn}
1580 Insert @var{template} using @var{dictionary} into @var{stream}.
1581 If @var{stream} is @code{nil}, then use the current buffer.
1584 @node Template Naming Conventions
1585 @chapter Template Naming Conventions
1587 For @srecode{} to work across languages reliably, templates need to
1588 follow a predictable pattern. For every language of similar nature
1589 (OO, functional, doc based) if they all provide the same base
1590 templates, then an application can be written against the base
1591 templates, and it will work in each of the supported language.
1593 Having consistent templates also makes it easy to use those templates
1594 from a user perspective during basic interactive insertion via
1595 @code{srecode-minor-mode}.
1598 NOTES ON THIS CHAPTER:
1600 These conventions are being worked on. Check w/ CEDET-DEVEL mailing
1601 list if you want to support a language, or write an application and
1602 provide your opinions on this topic. Any help is appreciated.
1605 @section Context: File
1607 Each language should support the @code{file:empty} template. This
1608 will generally use the default copyright insertion mechanism.
1610 @section Context: Declaration
1612 Functional languages should attempt to support the following:
1616 A standalone function. Not a method, external method, or other.
1618 A method belonging to some class declared outside the textual bounds
1619 of that class' declaration.
1623 A data type. If the language supports several types of datatypes
1624 then do not use this, use more specific ones instead.
1626 For OO languages, use this instead of @code{type}.
1631 For any @semantic{} tag class in your language, you will likely want
1632 to have a corresponding template.
1634 In order for the @srecode{} function
1635 @code{srecode-semantic-insert-tag} to work, you can create templates
1636 similar to those mentioned above, except with @code{-tag} appended to
1637 the end. This lets a template like @code{function} have user
1638 conveniences when referencing @code{function-tag}, while also
1639 allowing the tag inserter to do its job with a simpler template.
1641 @section Context: Classdef
1643 Inside a class definition. These are to be inserted inside the
1644 textual bounds of a class declaration.
1648 This would be a method of the class being inserted into.
1651 Like @code{function} but specific to alloc/delete of an object.
1653 This would be a field of the class being inserted into.
1656 @section Context: Code
1658 Inside a body of code, such as a function or method body.
1660 ---no conventions yet.
1662 @section Standard Dictionary Values
1664 For these variables to be useful, standard names should be used.
1665 These values could be provided directly from a Semantic tag, or by an
1670 The name of the declaration being created.
1672 If the item belongs to some parent type, it would be the full name of
1673 that type, including namespaces.
1675 A datatype name for a variable, or the return value of a function.
1677 If there is some documentation associated with the item, then DOC
1678 should contain the value. (Optional)
1680 The ARGS variable defines a section for 0 or more arguments to a function
1681 or method. Each entry in ARGS will follow the rest of these naming
1682 conventions, such as for NAME and TYPE.
1685 For templates used by @code{srecode-semantic-insert-tag}, there is
1686 also the following useful dictionary values.
1690 A special insertion value TAG@. You can use semantic functions to turn
1691 the tag into a string.
1694 Default value for a variable.
1697 @node Inserting Tag Lists
1698 @chapter Inserting Tag Lists
1700 Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for
1701 @srecode{} is to convert lists of tags, as produced by @semantic{}
1704 A single function provides the interface for programs to do this, but
1705 it requires any particular language to have provided the correct
1706 templates to make it work.
1708 @defun srecode-semantic-insert-tag tag &optional style-option point-insert-fcn &rest dict-entries
1709 @anchor{srecode-semantic-insert-tag}
1710 Insert @var{tag} into a buffer using srecode templates at point.
1712 Optional @var{style-option} is a list of minor configuration of styles,
1713 such as the symbol @code{'prototype} for prototype functions, or
1714 @code{'system} for system includes, and @code{'doxygen}, for a doxygen style
1717 Optional third argument @var{point-insert-fcn} is a hook that is run after
1718 @var{tag} is inserted that allows an opportunity to fill in the body of
1719 some thing. This hook function is called with one argument, the @var{tag}
1722 The rest of the arguments are @var{dict-entries}. @var{dict-entries}
1723 is of the form ( @var{name1} @var{value1} @var{name2} @var{value2} @dots{} NAMEn VALUEn).
1725 The exact template used is based on the current context.
1726 The template used is found within the toplevel context as calculated
1727 by @dfn{srecode-calculate-context}, such as @code{declaration}, @code{classdecl},
1730 For various conditions, this function looks for a template with
1731 the name @var{class}-tag, where @var{class} is the tag class. If it cannot
1732 find that, it will look for that template in the
1733 @code{declaration}context (if the current context was not @code{declaration}).
1735 If @var{prototype} is specified, it will first look for templates with
1736 the name @var{class}-tag-prototype, or @var{class}-prototype as above.
1738 See @dfn{srecode-semantic-apply-tag-to-dict} for details on what is in
1739 the dictionary when the templates are called.
1741 This function returns to location in the buffer where the
1742 inserted tag @var{ends}, and will leave point inside the inserted
1743 text based on any occurrence of a point-inserter. Templates such
1744 as @dfn{function} will leave point where code might be inserted.
1748 @node Application Writing
1749 @chapter Application Writing
1751 The main goal of @srecode{} is to provide a strong platform for
1752 writing code generating applications.
1754 Any templates that are application specific should make an application
1755 declaration for each template file they use. This prevents those
1756 templates from being used outside of that application.
1758 For example, add this to a file:
1760 set application "getset"
1763 In your application Emacs Lisp code, you would then load those
1764 templates. A typical initialization would look like this:
1767 (srecode-load-tables-for-mode major-mode)
1768 (srecode-load-tables-for-mode major-mode 'getset)
1771 These two lines will load in the base templates for the major mode,
1772 and then the application specific templates.
1774 @defun srecode-load-tables-for-mode mmode &optional appname
1775 @anchor{srecode-load-tables-for-mode}
1776 Load all the template files for @var{mmode}.
1777 Templates are found in the SRecode Template Map.
1778 See @dfn{srecode-get-maps} for more.
1779 @var{appname} is the name of an application. In this case,
1780 all template files for that application will be loaded.
1784 todo: Add examples. Most core stuff is already described above.
1787 @node GNU Free Documentation License
1788 @appendix GNU Free Documentation License
1789 @include doclicense.texi