3 @setfilename ../../info/srecode.info
4 @set TITLE SRecoder Manual
5 @set AUTHOR Eric M. Ludlam
6 @settitle @value{TITLE}
7 @documentencoding UTF-8
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--2014 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 RET
112 M-x global-srecode-minor-mode 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 TAB on a field will move you to the next field.
281 @node SRecode Minor Mode
282 @chapter SRecode Minor Mode
284 The Semantic Recode minor mode enables a keymap and menu that provides
285 simple access to different templates or template applications.
287 The key prefix is @key{C-c /}.
289 If the variable @code{srecode-takeover-INS-key} is set, then the key
290 @key{<insert>} can also be used.
292 The most important key is bound to @code{srecode-insert} which is
293 @key{C-c / /}, or @key{insert insert}. @ref{Quick Start}.
295 Major keybindings are:
299 Insert a template whose name is typed into the minibuffer.
300 @item C-c / <lower case letter>
301 Reserved for direct binding of simple templates to keys using a
302 keybinding command in the template file.
303 @item C-c / <upper case letter>
304 Reserved for template applications (Such as comment or get/set inserter.)
306 Edit the code of a template.
308 Insert template again. This will cause the previously inserted
309 template to be inserted again.
312 @section Field Editing
314 By default, when inserting a template, if the user needs to enter text
315 to fill in a part of the template, then the minibuffer is used to
316 query for that information. SRecode also supports a field-editing mode
317 that can be used instead. To enable it set:
319 @defun srecode-insert-ask-variable-method
320 @anchor{srecode-insert-ask-variable-method}
321 Determine how to ask for a dictionary value when inserting a template.
322 Only the @var{ASK} style inserter will query the user for a value.
323 Dictionary value references that ask begin with the ? character.
327 Prompt in the minibuffer as the value is inserted.
329 Use the dictionary macro name as the inserted value,
330 and place a field there. Matched fields change together.
333 @b{NOTE}: The field feature does not yet work with XEmacs.
336 Field editing mode is supported in newer versions of Emacs. You
337 will not be prompted to fill in values while the template is
338 inserted. Instead, short regions will be highlighted, and the cursor
339 placed in a field. Typing in the field will then fill in the value.
340 Several fields might be linked together. In that case, typing in one
341 area will modify the other linked areas. Pressing TAB will move
342 between editable fields in the template.
344 Once the cursor moves out of the are inserted by the template, all the
347 @b{NOTE}: Some conveniences in templates, such as completion, or
348 character restrictions are lost when using field editing mode.
350 @node Template Writing
351 @chapter Template Writing
352 @anchor{@code{SRecode-template-mode}}
354 @code{srecode-template-mode} is the major mode used for designing new
355 templates. @srecode{} files (Extension @file{.srt}) are made up of
356 variable settings and template declarations.
358 Here is an overview of the terminology you will need for the next few
363 A file with a @file{.srt} extension which contains settings,
364 variables, and templates.
366 One named entity which represents a block of text that will be
367 inserted. The text is compiled into a sequence of insertable
368 entities. The entities are string constants, and macros.
370 A macro is a text sequence within template text that is replaced with
373 A table of variable names and values.
375 A dictionary that is subordinate under another dictionary as a value
378 A variable is an entry in a dictionary which has a value.
382 * Variables:: Creating special and regular variables.
383 * Templates:: Creating templates
384 * Contexts:: Templates are grouped by context
385 * Prompts:: Setting prompts for interactive insert macros
391 Variables can be set up and used in templates. Many variables you may
392 use are set up via template arguments, but some may be preferences a
393 user can set up that are used in system templates.
395 When expanding a template, variables are stored in a @dfn{dictionary}.
396 Dictionary entries are variables. Variables defined in templates can
397 have string like values.
399 A variable can be set like this:
401 set VARNAME "some value"
404 Note that a VARIABLE is a name in a dictionary that can be used in a
405 MACRO in a template. The macro references some variable by name.
408 * String Values:: Basic Variable values
409 * Multi-string Values:: Complex variable values
410 * Section Show:: Enabling the display of a named section.
411 * Special Variables:: Variables with special names
412 * Automatic Loop Variables:: Variables automatically set in section loops.
413 * Compound Variable Values:: Compound Variable Values
417 @subsection String Values
419 Variables can be set to strings. Strings may contain newlines or any
420 other characters. Strings are interpreted by the Emacs Lisp reader so
421 @code{\n}, @code{\t}, and @code{\"} work.
423 When a string is inserted as part of a template, nothing within the
424 string is interpreted, such as template escape characters.
426 @node Multi-string Values
427 @subsection Multi-string Values
429 A variable can be set to multiple strings. A compound value is
430 usually used when you want to use dictionary entries as part of a
433 Multi-string variable values are set like string values except there
434 are more than one. For example
437 set NAME "this" "-mode"
440 These two strings will be concatenated together.
442 A more useful thing is to include dictionary variables and concatenate
443 those into the string. Use the ``macro'' keyword to include the name
444 of a variable. This is like macros in a template. For example:
447 set NAME macro "MODE" "-mode"
450 will extract the value of the dictionary variable MODE and append
451 ``-mode'' to the end.
454 @subsection Section Show
456 To set a variable to show a template section, use the @code{show}
457 command. Sections are blocks of a template wrapped in section macros.
458 If there is a section macro using @var{NAME} it will be shown for each
459 dictionary associated with the @var{NAME} macro.
465 This will enable that section.
468 NOTE: May 11, 2008: I haven't used this yet, so I don't know if it works.
471 @node Special Variables
472 @subsection Special Variables
474 Some variables have special meaning that changes attributes when
475 templates are compiled, including:
479 This is the character sequence that escapes from raw text to template
480 macro names. The ability to change the escape characters are key for
481 enabling @srecode{} templates to work across many kinds of languages.
483 This is the character sequence that escapes the end of a template
492 This is the major mode, as a string with the full Emacs Lisp symbol in
493 it. All templates in this file will be installed into the template
494 table for this major mode.
496 Multiple template files can use the same mode, and all those templates
497 will be available in buffers of that mode.
501 set mode "emacs-lisp-mode"
505 The priority of a file is a number in a string constant that
506 indicates where it lies in the template search order. System
507 templates default to low priority numbers. User templates default to
508 high priority numbers. You can specify the priority of your template
509 to insert it anywhere in the template search list.
511 If there are multiple templates with the same context and name, the
512 template with the highest priority number will be used.
514 If multiple files have the same priority, then then sort order is
515 unpredictable. If no template names match, then it doesn't matter.
523 If a template file contains templates only needed for a particular
524 application, then specify an application. Template files for an
525 application are stored in the template repository, but are not used in
526 the generic template insertion case.
528 The application with a particular name will access these templates
533 set application "document"
537 If a template file contains templates, or template overrides specific
538 to a set of files under a particular directory, then that template
539 file can specify a ``project'' that it belongs to.
541 Set the ``project'' special variable to a directory name. Only files
542 under that directory will be able to access the templates in that
545 Any template file that has a project specified will get have a
546 priority that is set between SRecode base templates, and user defined
549 Templates can be compiled via a project system, such as EDE@. EDE
550 loaded templates will get a @var{project} set automatically.
554 set project "/tmp/testproject"
559 If you need to insert the characters that belong to the variables
560 @code{escape_start} or @code{escape_end}, then place those into
561 a variable. For example
569 @node Automatic Loop Variables
570 @subsection Automatic Loop Variables
572 When section macros are used, that section is repeated for each
573 subdictionary bound to the loop variable.
575 Each dictionary added will automatically get values for positional
576 macros which will enable different @var{sections}. The automatic
577 section variables are.
580 @item @var{first}---The first entry in the table.
581 @item @var{notfirst}---Not the first entry in the table.
582 @item @var{last}---The last entry in the table
583 @item @var{notlast}---Not the last entry in the table.
586 @node Compound Variable Values
587 @subsection Compound Variable Values
589 A variable can also have a compound value. This means the value of
590 the variable is an @EIEIO{} object, which is a subclass of
591 @code{srecode-dictionary-compound-value}.
593 New compound variables can only be setup from Lisp code. See
594 @ref{Compound Dictionary Values} for details on setting up compound
600 A template represents a text pattern that can be inserted into
603 A basic template is declared like this:
606 template TEMPLATENAME :arg1 :arg2
607 "Optional documentation string"
609 The text to your template goes here.
614 Templates are stored in a template table by name, and are inserted by
615 the @var{templatename} provided.
617 The documentation string is optional. This documentation string will
618 be used to aid users in selecting which template they want to use.
620 The code that makes up the raw template occurs between the lines that
621 contain the text "-----".
624 * Template Section Dictionaries:: Template Scoped Macro values
625 * Template Macros:: Macros occurring in template patterns
628 @node Template Section Dictionaries
629 @subsection Template Section Dictionaries
631 To add variable values to section dictionaries used within a specific
632 template, you can add them to the beginning of the template
633 declaration like this:
636 template TEMPLATENAME :arg1 :arg2
637 "Optional documentation string"
638 sectiondictionary "A"
641 A beginning line @{@{NAME@}@}
642 @{@{#A@}@}Optional string @{@{NAME@}@} here@{@{/A@}@}
647 In this example, the @var{NAME} variable gets the value ``foo'', but
648 only while it is inside section macro A@. The outer scoped NAME will
651 This is particularly useful while using an include macro to pull in a
652 second template. In this way, you can pass values known from one
653 template to a subordinate template where some value is not known.
655 From the Emacs Lisp default template file, a syntax table is just a
656 variable with a specialized value.
658 If a variable is declared like this (where $ is the escape character):
661 template variable :el
670 then you can see that there is a NAME and DOC that is needed.
671 The @code{^} point inserter is also a handy key here.
673 The syntax table wants a variable, but knows the values of some of
674 these variables, and can recast the problem like this by using
675 template specific @code{sectiondictionary} macro declarations.
678 template syntax-table
679 "Create a syntax table."
680 sectiondictionary "A"
681 set NAME macro "?MODESYM" "-mode-syntax-table"
682 set DOC "Syntax table used in " macro "?MODESYM" " buffers."
685 (let ((table (make-syntax-table (standard-syntax-table))))
686 (modify-syntax-entry ?\; ". 12" table) ;; SEMI, Comment start ;;
693 In this way, @var{NAME} can be set as a user posed question for
694 @var{MODESYM} with ``-mode-syntax-table'' appended. A simplified doc
695 string will also be inserted.
697 Lastly, the @var{A} section contains more macro text which is inserted
698 at the @code{^} point marker.
700 By creating useful base templates for things like function or variable
701 declarations, and recycling them in higher-order templates, an end
702 user can override the basic declarator, and the higher order templates
703 will then obey the new format, or perhaps even work in more than one
706 @node Template Macros
707 @subsection Template Macros
709 Template macros occur in the template text. The default escape
710 characters are ``@{@{`` and ``@}@}'', though they can be changed
711 in the top-level variables. See @ref{Variables}.
713 Thus, if you have the template code that looks like this:
716 ;; Author: @{@{AUTHOR@}@}
719 Then the text between @{@{ and @}@} are a macro, and substituted by
720 the value of the variable @var{AUTHOR}.
722 Macros can be specialized to be more than just a text string. For
723 example, the macro above could be augmented with an Emacs Lisp
727 ;; Author: @{@{AUTHOR:upcase@}@}
730 In this case, the Emacs Lisp function @code{upcase} will be called on
731 the text value of the @var{AUTHOR} variable.
733 Macros can also be specialized to have different behaviors by using a
734 prefix, non-alpha character or symbol. For example:
737 @{@{! This is a comment inside macro escape characters @}@}
740 shows that the ``!'' symbol is for comments.
742 Alternately, a macro could query the user during insertion:
745 (defun @{@{?NAME@}@} ()
747 ) ;; End of @{@{NAME@}@}
750 the ``?'' symbol indicates that if the symbol @var{NAME} isn't in the
751 dictionary, then the user should be queried for the @var{NAME}
752 variable. If @var{NAME} appears again in the template, the original
753 value specified by the user will be inserted again.
755 If the text from a dictionary value is to be placed in column format,
756 you can use the ``|'' symbol to indicate you want column control. For
760 | this | that |@{@{#A@}@}
761 | @{@{|THIS:4@}@} | @{@{|THAT:4@}@} |@{@{/A@}@}
764 For each repeated section ``#A'' the dictionary values for @var{THIS}
765 and @var{THAT} will be inserted and either trimmed to, or expanded to
766 4 characters in width.
768 Macros that are prefixed with the ``#'' symbol denote a section. A
769 macro of the same name with a ``/'' prefix denotes the end of that
774 Here is some text describing moose.
778 In this example if the section MOOSE was ``shown'' in the active
779 dictionary, then the text between the # and / macros will also be
782 All the text and macros within a section are either not shown at all
783 (if that section is not 'visible') or the section is shown one time
784 for each dictionary added to that symbol.
785 @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 prompting 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 language. The name @code{foo} is not ambiguous because each is in
867 Some templates use prompting 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 occurrences 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-populate 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 associate 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
1001 a new dictionary if there is already one in place. Also, don't add
1002 @var{FIRST}/@var{LAST} entries.
1003 These entries are not needed when we are just showing a section.
1005 Each dictionary added will automatically get values for positional macros
1006 which will enable @var{SECTIONS} to be enabled.
1010 The first entry in the table.
1012 Not the first entry in the table.
1014 The last entry in the table
1016 Not the last entry in the table.
1019 Adding a new dictionary will alter these values in previously
1020 inserted dictionaries.
1023 @node Compound Dictionary Values
1024 @section Compound Dictionary Values
1026 If you want to associate a non-string value with a dictionary
1027 variable, then you will need to use a compound value. Compound
1028 dictionary values are derived using @EIEIO{} from a base class for
1029 handling arbitrary data in a macro.
1031 @deffn Type srecode-dictionary-compound-value
1032 @anchor{srecode-dictionary-compound-value}
1033 A compound dictionary value.
1034 Values stored in a dictionary must be a @var{string},
1035 a dictionary for showing sections, or an instance of a subclass
1038 Compound dictionary values derive from this class, and must
1039 provide a sequence of method implementations to convert into
1043 Your new subclass of the compound value needs to implement these
1046 @defun srecode-compound-toString cp function dictionary
1047 @anchor{srecode-compound-toString}
1048 Convert the compound dictionary value @var{cp} to a string.
1049 If @var{function} is non-@code{nil}, then @var{function} is somehow applied to an aspect
1050 of the compound value. The @var{function} could be a fraction
1051 of some function symbol with a logical prefix excluded.
1054 The next method is for dumping out tables during debugging.
1056 @defun srecode-dump cp &optional indent
1057 @anchor{srecode-dump}
1058 Display information about this compound value.
1062 Here is an example of wrapping a semantic tag in a compound value:
1065 (defclass srecode-semantic-tag (srecode-dictionary-compound-value)
1066 ((prime :initarg :prime
1069 "This is the primary insertion tag.")
1071 "Wrap up a collection of semantic tag information.
1072 This class will be used to derive dictionary values.")
1074 (defmethod srecode-compound-toString((cp srecode-semantic-tag)
1077 "Convert the compound dictionary value CP to a string.
1078 If FUNCTION is non-nil, then FUNCTION is somehow applied to an
1079 aspect of the compound value."
1081 ;; Just format it in some handy dandy way.
1082 (semantic-format-tag-prototype (oref cp :prime))
1083 ;; Otherwise, apply the function to the tag itself.
1084 (funcall function (oref cp :prime))
1088 @node Argument Resolution
1089 @section Argument Resolution
1091 Some dictionary entries can be set via template arguments in the
1092 template declaration. For examples of template arguments, see
1093 @ref{Template Argument Dictionary Entries}.
1095 You can resolve an argument list into a dictionary with:
1097 @defun srecode-resolve-arguments temp dict
1098 @anchor{srecode-resolve-arguments}
1099 Resolve all the arguments needed by the template @var{temp}.
1100 Apply anything learned to the dictionary @var{dict}.
1103 @node Creating new Arguments
1104 @section Creating new Arguments
1106 You can create new arguments for use in template files by writing new
1107 Emacs Lisp functions. Doing so is easy. Here is an example for the
1108 @code{:user} argument:
1111 (defun srecode-semantic-handle-:user (dict)
1112 "Add macros into the dictionary DICT based on the current :user."
1113 (srecode-dictionary-set-value dict "AUTHOR" (user-full-name))
1114 (srecode-dictionary-set-value dict "LOGIN" (user-login-name))
1119 In this case, a function with the name prefix
1120 @code{srecode-semantic-handle-} that ends in @code{:user} creates a
1121 new argument @code{:user} that can be used in a template.
1123 Your argument handler must take one argument @var{dict}, which is the
1124 dictionary to fill in. Inside your function, you can do whatever you
1125 want, but adding dictionary values is the right thing.
1127 @node Querying a Dictionary
1128 @section Querying a Dictionary
1130 When creating a new argument, it may be useful to ask the dictionary
1131 what entries are already set there, and conditionally create new
1132 entries based on those.
1134 In this way, a template author can get additional logic through more
1137 @defun srecode-dictionary-lookup-name dict name
1138 @anchor{srecode-dictionary-lookup-name}
1139 Return information about the current @var{DICT}'s value for @var{NAME}.
1140 @var{DICT} is a dictionary, and @var{NAME} is a string that is the name of
1141 a symbol in the dictionary.
1142 This function derives values for some special NAMEs, such as @var{FIRST}
1148 @node Template Argument Dictionary Entries
1149 @section Template Argument Dictionary Entries
1151 When a dictionary is initialized for a template, then the dictionary
1152 will be initialized with a predefined set of macro values.
1154 A template of the form:
1157 template template-name :arg1 :arg2
1159 Your template goes here
1163 specifies two arguments :arg1, and :arg2.
1165 The following built-in simple arguments are available:
1169 * Semantic Arguments::
1170 * Language Arguments::
1173 @node Base Arguments
1174 @subsection Base Arguments
1176 @subsubsection Argument :indent
1178 Supplies the @code{INDENT} macro. When @code{INDENT} is non-@code{nil}, then
1179 each line is individually indented with
1180 @code{indent-according-to-mode} during macro processing.
1182 @subsubsection Argument :blank
1184 Specifying this argument adds a special @code{:blank} handler at the
1185 beginning and end of the template. This handler will insert @code{\n}
1186 if the insertion point is not on a line by itself.
1188 @subsubsection Argument :region
1190 If there is an active region via @code{transient-mark-mode}, or
1191 @code{mouse-drag-region}, then the @code{REGION} section will be
1194 In addition, @code{REGIONTEXT} will be set to the text in the region,
1195 and that region of text will be ``killed'' from the current buffer.
1197 If standard-output is NOT the current buffer, then the region will not
1198 be deleted. In this way, you can safely use @code{:region} using
1199 templates in arbitrary output streams.
1201 @subsubsection Argument :user
1203 Sets up variables about the current user.
1207 Value of the Emacs function @code{user-full-name}
1209 Current Emacs user's email address.
1211 Current Emacs user's login name.
1213 Current Emacs user's login ID.
1215 This Emacs sessions' init file.
1218 @subsubsection Argument :time
1220 Sets up variables with the current date and time.
1226 The current month as a number.
1228 The current month name, unabbreviated.
1230 The current day as a number.
1232 The current day of the week as an abbreviated name
1234 The current hour in 24 hour format.
1236 The current hour in 12 hour format.
1238 Locale equivalent of AM or PM@. Useful with HOUR12.
1244 The timezone string.
1246 The Locale supported date (%D).
1248 The Locale supported time format (%X).
1251 @subsubsection Argument :file
1253 Sets up variables with details about the current file.
1257 The filename without the directory part of the current buffer.
1259 The filename without the directory or extension
1261 The filename extension.
1263 The directory in which the current buffer resides.
1265 Major mode of this buffer.
1267 Major mode of this buffer without ``-mode''.
1268 Useful for inserting the Emacs mode specifier.
1270 Show the section RCS if there is a CVS or RCS directory here.
1273 @subsubsection Argument :system
1275 Sets up variables with computer system information.
1279 The ``system-configuration''.
1281 The ``system-type''.
1283 The ``system-name''.
1285 The name of the machine Emacs derived mail ``comes from''.
1288 @subsubsection Argument :kill
1292 The top-most item from the kill ring.
1294 The second item in the kill ring.
1296 The third item in the kill ring.
1298 The fourth item in the kill ring.
1301 @node Semantic Arguments
1302 @subsection Semantic Arguments
1304 @subsubsection Argument :tag
1306 The :tag argument is filled in with information from Semantic.
1307 The tag in question is queried from the senator tag ring, or passed
1308 in from @srecode{} utilities that use tags in templates.
1312 This is a compound value for the tag in the current senator kill ring,
1313 or something handled via the variable
1314 @code{srecode-semantic-selected-tag}.
1316 @defvar srecode-semantic-selected-tag
1317 @anchor{srecode-semantic-selected-tag}
1318 The tag selected by a @code{:tag} template argument.
1319 If this is @code{nil}, then @code{senator-tag-ring} is used.
1322 Use the function part of a macro insert to extract obscure parts
1325 The name of the tag as a string.
1327 The data type of the tag as a string.
1330 If @var{tag} is a function, you will get these additional dictionary
1335 A Loop macro value. Each argument is inserted in ARGS@. To create a
1336 comma separated list of arguments, you might do this:
1339 @{@{#ARGS@}@}@{@{TYPE@}@} @{@{NAME@}@}@{@{#NOTLAST@}@},@{@{/NOTLAST@}@}@{@{/ARGS@}@}
1342 Within the section dictionaries for each argument, you will find both
1343 @var{NAME} and @var{TYPE}, in addition to the automatic section values
1344 for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}.
1346 The string name of the parent of this function, if the function is a
1347 method of some class.
1349 In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified.
1352 If @var{tag} is a variable, you will get these dictionary entries.
1356 Enabled if there is a @var{VALUE}.
1358 An entry in the @var{HAVEDEFAULT} subdictionary that represents the
1359 textual representation of the default value of this variable.
1362 If @var{tag} is a datatype, you will get these dictionary entries.
1366 Section dictionaries for the parents of this class. Each parent will
1369 Section dictionaries for all the implemented interfaces of this
1370 class. Each interface will have a @var{NAME}.
1373 Note that data type templates should always have a @code{@{@{^@}@}}
1374 macro in it where the core contents of that type will go. This is why
1375 data types don't have subdictionaries full of the slots in the classes
1378 @node Language Arguments
1379 @subsection language Arguments
1381 Each language typically has its own argument. These arguments can be
1382 used to fill in language specific values that will be useful.
1384 @subsubsection Argument :srt
1386 Used for SRecoder template files.
1390 The characters used for an escape start
1392 The characters used for an escape end
1395 @subsubsection Argument :cpp
1399 Shows this section if the current file is a header file.
1401 The opposite of @code{HEADER}.
1402 @item FILENAME_SYMBOL
1403 The current filename reformatted as a C friendly symbol.
1406 @subsection Argument :java
1409 @item FILENAME_AS_PACKAGE
1410 Converts the filename into text that would be suitable as a package
1412 @item FILENAME_AS_CLASS
1413 Converts the filename into text that would be suitable as a class-name
1414 for the main class in the file.
1415 @item CURRENT_PACKAGE
1416 Finds the occurrence of ``package'' and gets its value.
1419 @subsubsection Argument :el
1421 Sets @code{PRENAME}. This would be a common prefix from all the
1422 tags in the current buffer.
1424 Most Emacs Lisp packages have some common prefix used in a way similar
1425 to namespaces in other languages.
1427 @subsubsection Argument :el-custom
1431 The name of the Emacs Custom group that instances of @code{defcustom}
1434 The name of the Emacs Custom group that faces declared with
1435 @code{defface} ought to use.
1438 @subsubsection Argument :texi
1442 The current section level, such as @code{chapter} or @code{section}.
1444 The next level down, so if @code{LEVEL} is @code{chapter}, then
1445 @code{NEXTLEVEL} would be @code{section}.
1448 @subsubsection Argument :texitag
1450 The @code{:texitag} argument is like the @code{:tag} argument, except that
1451 additional variable @code{TAGDOC} is provided for each tag.
1453 The @code{TAGDOC} is filled with derived documentation from the tag in
1454 question, and that documentation is also reformatted to be mostly
1457 @subsection Argument :android
1459 The @code{:android} argument pulls in information from your current
1462 @@TODO - add more here.
1464 @node Developing Template Functions
1465 @chapter Developing Template Functions
1467 You can develop your own custom template insertion functions.
1468 Doing so is relatively simple, and requires that you write an Emacs
1471 If the built in commands don't provide enough options, you will need
1472 to write your own function in order to provide your dictionaries with
1473 the values needed for custom templates.
1475 In this way, you can build your own code generator for any language
1476 based on a set of predefined macros whos values you need to derive
1477 from Emacs Lisp code yourself.
1482 (defun my-srecode-insert (template-name)
1483 "Insert the template TEMPLATE-NAME into the current buffer at point."
1485 ;; Read in a template name.
1486 (interactive (list (srecode-read-template-name "Template Name: ")))
1487 (if (not (srecode-table))
1488 (error "No template table found for mode %s" major-mode))
1489 (let ((temp (srecode-template-get-table (srecode-table) template-name))
1491 ;; Create a new dictionary
1492 (newdict (srecode-create-dictionary)))
1495 (error "No Template named %s" template-name))
1497 ;; Add some values into the dictionary!
1498 (srecode-dictionary-set-value newdict "FOO" (my-get-value-of-foo))
1499 ;; Optionally show a section
1500 (srecode-dictionary-show-section newdict "BLARG")
1502 ;; Add in several items over a loop
1503 (let ((my-stuff (get-my-stuff-list)))
1505 (let ((subdict (srecode-dictionary-add-section-dictionary
1507 (srecode-dictionary-set-value subdict "NAME" (nth 0 my-stuff))
1508 (srecode-dictionary-set-value subdict "ARG" (nth 1 my-stuff))
1509 (srecode-dictionary-set-value subdict "MOOSE" (nth 2 my-stuff))
1511 (setq my-stuff (cdr my-stuff)))
1513 ;; Some templates have arguments that need to be resolved.
1514 (srecode-resolve-arguments temp newdict)
1517 (srecode-insert-fcn temp newdict)
1521 Lets look at the key functions involved above:
1523 @section Interactive Completion:
1525 @defun srecode-read-template-name prompt
1526 @anchor{srecode-read-template-name}
1527 Completing read for Semantic Recoder template names.
1528 @var{prompt} is used to query for the name of the template desired.
1531 @section Template Lookup
1533 Even if your program does not query the user for a template name, you
1534 will need to locate a template. First, you need to locate the table
1535 to look the template up in.
1537 @defun srecode-table &optional mode
1538 @anchor{srecode-table}
1539 Return the currently active Semantic Recoder table for this buffer.
1540 Optional argument @var{MODE} specifies the mode table to use.
1544 @defun srecode-template-get-table tab template-name &optional context application
1545 @anchor{srecode-template-get-table}
1546 Find in the template in mode table @var{TAB}, the template with @var{TEMPLATE-NAME}.
1547 Optional argument @var{CONTEXT} specifies a context a particular template
1549 Optional argument @var{APPLICATION} restricts searches to only template tables
1550 belonging to a specific application. If @var{APPLICATION} is @code{nil}, then only
1551 tables that do not belong to an application will be searched.
1554 For purposes of an @srecode{} application, it is important to decide
1555 what to call your application, and use that with this method call.
1557 @section Creating dictionaries
1559 Several dictionary calls are made in this example, including:
1561 @item srecode-create-dictionary
1562 @item srecode-dictionary-set-value
1563 @item srecode-dictionary-show-section
1564 @item srecode-dictionary-add-section-dictionary
1567 These are documented more fully @ref{Dictionaries}.
1569 Also used is @code{srecode-resolve-arguments}. To learn more about
1570 that, see @ref{Argument Resolution}.
1572 @section Template Insertion Commands
1574 There are several ways to insert a template. It is easiest to just
1575 start with the main entry point.
1577 @defun srecode-insert-fcn template dictionary &optional stream
1578 @anchor{srecode-insert-fcn}
1579 Insert @var{template} using @var{dictionary} into @var{stream}.
1580 If @var{stream} is @code{nil}, then use the current buffer.
1583 @node Template Naming Conventions
1584 @chapter Template Naming Conventions
1586 For @srecode{} to work across languages reliably, templates need to
1587 follow a predictable pattern. For every language of similar nature
1588 (OO, functional, doc based) if they all provide the same base
1589 templates, then an application can be written against the base
1590 templates, and it will work in each of the supported language.
1592 Having consistent templates also makes it easy to use those templates
1593 from a user perspective during basic interactive insertion via
1594 @code{srecode-minor-mode}.
1597 NOTES ON THIS CHAPTER:
1599 These conventions are being worked on. Check w/ CEDET-DEVEL mailing
1600 list if you want to support a language, or write an application and
1601 provide your opinions on this topic. Any help is appreciated.
1604 @section Context: File
1606 Each language should support the @code{file:empty} template. This
1607 will generally use the default copyright insertion mechanism.
1609 @section Context: Declaration
1611 Functional languages should attempt to support the following:
1615 A standalone function. Not a method, external method, or other.
1617 A method belonging to some class declared outside the textual bounds
1618 of that class' declaration.
1622 A data type. If the language supports several types of datatypes
1623 then do not use this, use more specific ones instead.
1625 For OO languages, use this instead of @code{type}.
1630 For any @semantic{} tag class in your language, you will likely want
1631 to have a corresponding template.
1633 In order for the @srecode{} function
1634 @code{srecode-semantic-insert-tag} to work, you can create templates
1635 similar to those mentioned above, except with @code{-tag} appended to
1636 the end. This lets a template like @code{function} have user
1637 conveniences when referencing @code{function-tag}, while also
1638 allowing the tag inserter to do its job with a simpler template.
1640 @section Context: Classdef
1642 Inside a class definition. These are to be inserted inside the
1643 textual bounds of a class declaration.
1647 This would be a method of the class being inserted into.
1650 Like @code{function} but specific to alloc/delete of an object.
1652 This would be a field of the class being inserted into.
1655 @section Context: Code
1657 Inside a body of code, such as a function or method body.
1659 ---no conventions yet.
1661 @section Standard Dictionary Values
1663 For these variables to be useful, standard names should be used.
1664 These values could be provided directly from a Semantic tag, or by an
1669 The name of the declaration being created.
1671 If the item belongs to some parent type, it would be the full name of
1672 that type, including namespaces.
1674 A datatype name for a variable, or the return value of a function.
1676 If there is some documentation associated with the item, then DOC
1677 should contain the value. (Optional)
1679 The ARGS variable defines a section for 0 or more arguments to a function
1680 or method. Each entry in ARGS will follow the rest of these naming
1681 conventions, such as for NAME and TYPE.
1684 For templates used by @code{srecode-semantic-insert-tag}, there is
1685 also the following useful dictionary values.
1689 A special insertion value TAG@. You can use semantic functions to turn
1690 the tag into a string.
1693 Default value for a variable.
1696 @node Inserting Tag Lists
1697 @chapter Inserting Tag Lists
1699 Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for
1700 @srecode{} is to convert lists of tags, as produced by @semantic{}
1703 A single function provides the interface for programs to do this, but
1704 it requires any particular language to have provided the correct
1705 templates to make it work.
1707 @defun srecode-semantic-insert-tag tag &optional style-option point-insert-fcn &rest dict-entries
1708 @anchor{srecode-semantic-insert-tag}
1709 Insert @var{tag} into a buffer using srecode templates at point.
1711 Optional @var{style-option} is a list of minor configuration of styles,
1712 such as the symbol @code{'prototype} for prototype functions, or
1713 @code{'system} for system includes, and @code{'doxygen}, for a doxygen style
1716 Optional third argument @var{point-insert-fcn} is a hook that is run after
1717 @var{tag} is inserted that allows an opportunity to fill in the body of
1718 some thing. This hook function is called with one argument, the @var{tag}
1721 The rest of the arguments are @var{dict-entries}. @var{dict-entries}
1722 is of the form ( @var{name1} @var{value1} @var{name2} @var{value2} @dots{} NAMEn VALUEn).
1724 The exact template used is based on the current context.
1725 The template used is found within the toplevel context as calculated
1726 by @dfn{srecode-calculate-context}, such as @code{declaration}, @code{classdecl},
1729 For various conditions, this function looks for a template with
1730 the name @var{class}-tag, where @var{class} is the tag class. If it cannot
1731 find that, it will look for that template in the
1732 @code{declaration}context (if the current context was not @code{declaration}).
1734 If @var{prototype} is specified, it will first look for templates with
1735 the name @var{class}-tag-prototype, or @var{class}-prototype as above.
1737 See @dfn{srecode-semantic-apply-tag-to-dict} for details on what is in
1738 the dictionary when the templates are called.
1740 This function returns to location in the buffer where the
1741 inserted tag @var{ends}, and will leave point inside the inserted
1742 text based on any occurrence of a point-inserter. Templates such
1743 as @dfn{function} will leave point where code might be inserted.
1747 @node Application Writing
1748 @chapter Application Writing
1750 The main goal of @srecode{} is to provide a strong platform for
1751 writing code generating applications.
1753 Any templates that are application specific should make an application
1754 declaration for each template file they use. This prevents those
1755 templates from being used outside of that application.
1757 For example, add this to a file:
1759 set application "getset"
1762 In your application Emacs Lisp code, you would then load those
1763 templates. A typical initialization would look like this:
1766 (srecode-load-tables-for-mode major-mode)
1767 (srecode-load-tables-for-mode major-mode 'getset)
1770 These two lines will load in the base templates for the major mode,
1771 and then the application specific templates.
1773 @defun srecode-load-tables-for-mode mmode &optional appname
1774 @anchor{srecode-load-tables-for-mode}
1775 Load all the template files for @var{mmode}.
1776 Templates are found in the SRecode Template Map.
1777 See @dfn{srecode-get-maps} for more.
1778 @var{appname} is the name of an application. In this case,
1779 all template files for that application will be loaded.
1783 todo: Add examples. Most core stuff is already described above.
1786 @node GNU Free Documentation License
1787 @appendix GNU Free Documentation License
1788 @include doclicense.texi