Commit | Line | Data |
---|---|---|
4c2dd4ee | 1 | \input texinfo |
ac1d9dde | 2 | @c %**start of header |
4c2dd4ee | 3 | @setfilename ../../info/srecode |
ac1d9dde EL |
4 | @set TITLE SRecoder Manual |
5 | @set AUTHOR Eric M. Ludlam | |
6 | @settitle @value{TITLE} | |
4c2dd4ee GM |
7 | |
8 | @c Merge all indexes into a single index for now. | |
9 | @c We can always separate them later into two or more as needed. | |
10 | @syncodeindex vr cp | |
11 | @syncodeindex fn cp | |
12 | @syncodeindex ky cp | |
13 | @syncodeindex pg cp | |
14 | @syncodeindex tp cp | |
ac1d9dde EL |
15 | @c %**end of header |
16 | ||
4c2dd4ee | 17 | @copying |
6bc383b1 | 18 | Copyright @copyright{} 2007--2014 Free Software Foundation, Inc. |
4c2dd4ee GM |
19 | |
20 | @quotation | |
21 | Permission is granted to copy, distribute and/or modify this document | |
22 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
23 | any later version published by the Free Software Foundation; with no | |
24 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' | |
25 | and with the Back-Cover Texts as in (a) below. A copy of the license | |
26 | is included in the section entitled ``GNU Free Documentation License''. | |
27 | ||
28 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
6bf430d1 | 29 | modify this GNU manual.'' |
4c2dd4ee GM |
30 | @end quotation |
31 | @end copying | |
32 | ||
33 | @dircategory Emacs misc features | |
34 | @direntry | |
f9405d87 | 35 | * SRecode: (srecode). Semantic template code generator. |
4c2dd4ee | 36 | @end direntry |
ac1d9dde EL |
37 | |
38 | @titlepage | |
39 | @sp 10 | |
4c2dd4ee | 40 | @center @titlefont{SRecode} |
ac1d9dde | 41 | @vskip 0pt plus 1 fill |
4c2dd4ee | 42 | @center by @value{AUTHOR} |
ac1d9dde EL |
43 | @end titlepage |
44 | ||
45 | @macro semantic{} | |
4c2dd4ee | 46 | @i{Semantic} |
ac1d9dde EL |
47 | @end macro |
48 | ||
49 | @macro EIEIO{} | |
50 | @i{EIEIO} | |
51 | @end macro | |
52 | ||
53 | @macro srecode{} | |
54 | @i{SRecode} | |
55 | @end macro | |
56 | ||
57 | @node Top | |
58 | @top @value{TITLE} | |
59 | ||
60 | @srecode{} is the @i{Semantic Recoder}. Where @semantic{} will parse | |
61 | source files into lists of tags, the @i{Semantic Recoder} will aid in | |
62 | converting @semantic{} tags and various other information back into | |
63 | various types of code. | |
64 | ||
65 | While the @srecode{} tool provides a template language, templates for | |
66 | several languages, and even a sequence of heuristics that aid the user | |
67 | in choosing a template to insert, this is not the main goal of | |
68 | @srecode{}. | |
69 | ||
70 | The goal of @srecode{} is to provide an application framework where | |
71 | someone can write a complex code generator, and the underlying | |
72 | template commonality allows it to work in multiple languages with | |
73 | ease. | |
74 | ||
4c2dd4ee GM |
75 | @ifnottex |
76 | @insertcopying | |
77 | @end ifnottex | |
78 | ||
ac1d9dde EL |
79 | @menu |
80 | * Quick Start:: Basic Setup for template insertion. | |
81 | * User Templates:: Custom User Templates | |
82 | * Parts of SRecode:: Parts of the system | |
83 | * SRecode Minor Mode:: A minor mode for using templates | |
84 | * Template Writing:: How to write a template | |
85 | * Dictionaries:: How dictionaries work | |
86 | * Developing Template Functions:: How to write your own template insert functions. | |
87 | * Template Naming Conventions:: Creating a set of core templates | |
88 | * Inserting Tag Lists:: Inserting Semantic tags via templates | |
89 | * Application Writing:: Writing an @srecode{}r application | |
4c2dd4ee | 90 | * GNU Free Documentation License:: The license for this documentation. |
ac1d9dde EL |
91 | * Index:: |
92 | @end menu | |
93 | ||
94 | ||
95 | @node Quick Start | |
96 | @chapter Quick Start | |
97 | ||
98 | When you install CEDET and enable @srecode{}, an @code{SRecoder} menu | |
99 | item should appear. | |
100 | ||
101 | To toggle @srecode{} minor mode on and off use: | |
102 | ||
103 | @example | |
104 | M-x srecode-minor-mode RET | |
105 | @end example | |
106 | or | |
107 | @example | |
108 | M-x global-srecode-minor-mode RET | |
109 | @end example | |
110 | ||
111 | or add | |
112 | ||
113 | @example | |
114 | (srecode-minor-mode 1) | |
115 | @end example | |
116 | ||
117 | into a language hook function to force it on (which is the default) or | |
118 | pass in @code{-1} to force it off. | |
119 | ||
120 | See @ref{SRecode Minor Mode} for more on using the minor mode. | |
121 | ||
122 | Use the menu to insert templates into the current file. | |
123 | ||
124 | You can add your own templates in @file{~/.srecode}, or update the | |
125 | template map path: | |
126 | ||
127 | @deffn Option srecode-map-load-path | |
128 | @anchor{srecode-map-load-path} | |
129 | Global load path for SRecode template files. | |
130 | @end deffn | |
131 | ||
132 | ||
133 | Once installed, you can start inserting templates using the menu, or | |
134 | the command: | |
135 | ||
136 | @deffn Command srecode-insert template-name &rest dict-entries | |
137 | @anchor{srecode-insert} | |
138 | Insert the template @var{template-name} into the current buffer at point. | |
139 | @var{dict-entries} are additional dictionary values to add. | |
140 | @end deffn | |
141 | ||
142 | SRecode Insert will prompt for a template name. Template names are | |
143 | specific to each major mode. A typical name is of the form: | |
144 | @code{CONTEXT:NAME} where a @var{CONTEXT} might be something like | |
145 | @code{file} or @code{declaration}. The same @var{NAME} can occur in | |
146 | multiple contexts. | |
147 | ||
148 | @node User Templates | |
149 | @chapter User Templates | |
150 | ||
151 | @srecode{} builds and maintains a map of all template files. The root | |
152 | template files resides in the @srecode{} distribution. User written | |
153 | templates files are saved in @file{~/.srecode}, along with the | |
154 | @srecode{} map file. | |
155 | ||
156 | @defvar srecode-map-save-file | |
157 | @anchor{srecode-map-save-file} | |
158 | The save location for SRecode's map file. | |
159 | @end defvar | |
160 | ||
161 | Template files end with a @file{.srt} extension. Details on how to | |
162 | write templates are in @ref{Template Writing}. | |
163 | ||
164 | Each template file you write is dedicated to a single major mode. In | |
165 | it, you can write templates within the same context and with the same | |
166 | name as core templates. You can force your templates to override the | |
167 | core templates for a particular major mode by setting the | |
168 | priority. See @ref{Special Variables}. | |
169 | ||
170 | To get going quickly, open a new @file{.srt} file. It will start in | |
171 | the @srecode{} template writing mode. Use the @srecode{} minor mode | |
172 | menu to insert the @code{empty} file template. | |
173 | ||
174 | When using templates in other modes (such as C++ or Emacs Lisp | |
175 | templates), use the ``Edit Template'' menu to find a template you | |
176 | would like to update. Copy it into your user template file, and | |
177 | change it. | |
178 | ||
179 | If you were to update @code{declaration:function} in your user | |
180 | template file, then you would get this new template instead of the one | |
181 | that comes with @srecode{}. Higher level applications should always | |
182 | use @code{declaration:function} when generating their own code, so | |
183 | higher level templates will then adopt your changes to | |
184 | @code{declaration:function} into themselves. | |
185 | ||
186 | You can also override variables. Core variables are stored in the | |
187 | @srecode{} root template file @file{default.srt}, and that contains | |
188 | the copyright usually used, and some basic file setup formats. | |
189 | Override variables like this by specifying a @code{mode} of | |
190 | @code{default} like this: | |
191 | ||
192 | @example | |
193 | set mode "default" | |
194 | @end example | |
195 | ||
196 | @node Parts of SRecode | |
197 | @chapter Parts of SRecode | |
198 | ||
199 | The @srecode{} system is made up of several layers which work together | |
200 | to generate code. | |
201 | ||
202 | @section Template Layer | |
203 | The template layer provides a way to write, and compile templates. The | |
204 | template layer is the scheme used to insert text into an Emacs buffer. | |
205 | ||
206 | The @srecode{} template layer is more advanced than other modes like the | |
207 | Emacs packages @code{skeleton} or @code{tempo} in that it allows | |
208 | multiple layers of templates to be created with the same names. This | |
209 | means that @srecode{} can provide a wide range of templates, and users | |
210 | can override only the small sections they want, instead of either | |
211 | accepting someone else's template, or writing large new templates of | |
212 | their own. | |
213 | ||
214 | Templates are written in @file{.srt} files. You can learn how to | |
215 | author new @file{.srt} files @ref{Template Writing}. | |
216 | ||
217 | While the template system was designed for @srecode{} based | |
218 | applications it can also be used independently for simple template | |
219 | insertion during typical coding. | |
220 | ||
221 | @section Template Manager | |
222 | Once templates have been written, a scheme for loading and selecting | |
223 | templates is needed. The template manager has a loader for finding | |
224 | template files, and determining which templates are relevant to the | |
225 | current buffer. Template files are sorted by priority, with user | |
226 | templates being found first, and system level default templates last. | |
227 | Templates are also sorted by application. Each application has its | |
cccaebd2 | 228 | own templates, and are kept separate from the generic templates. |
ac1d9dde EL |
229 | |
230 | @section Dictionary | |
231 | Dictionaries contain values associated with variable. Variables are | |
232 | used in macros in a template. Variables are what allows a generic | |
233 | template such as a function to be made specific, such as a function | |
234 | named foo. The value of a variable can be one of three things; a | |
235 | string, a list of more dictionaries, or a special | |
236 | @code{srecode-dictionary-compound-value} object subclass. See | |
237 | @ref{Variables} for more. | |
238 | ||
239 | @section Template Insertion | |
240 | The template insertion layer involves extensions to the basic template | |
241 | layer. A wide range of custom variables are available for mixing derived | |
242 | data as macros into the plain text of a template. | |
243 | ||
244 | In addition, templates can be declared with arguments. These | |
245 | arguments represent predetermined sets of dictionary values, such as | |
246 | features of the current file name, user name, time, etc. | |
247 | ||
248 | Some arguments are major-mode specific, such as the @code{:el} or | |
249 | @code{:cpp} arguments. | |
ac1d9dde EL |
250 | |
251 | @section Template Insertion Context | |
252 | A context can be provided for templates in a file. This helps | |
253 | auto-selection of templates by name, or allows templates in different | |
254 | contexts to have the same name. Some standard contexts are | |
255 | @code{file}, @code{declaration}, and @code{classdecl}. | |
256 | ||
257 | A context can be automatically derived as well based on the parsing | |
258 | state from @i{Semantic}. @inforef{Top, Semantic Manual, semantic}. | |
ac1d9dde EL |
259 | |
260 | @section Applications | |
261 | Commands that do a particular user task which involves also writing | |
262 | Emacs Lisp code. Applications are at the top layer. These | |
263 | applications have their own template files and logic needed to fill in | |
264 | dictionaries or position a cursor. SRecode comes with an example | |
265 | @code{srecode-document} application for creating comments for Semantic | |
266 | tags. The CEDET application @i{EDE} has a project type that is an | |
267 | @srecode{} application. | |
268 | ||
269 | @section Field Editing | |
270 | If the variable @code{srecode-insert-ask-variable-method} is set to | |
271 | 'field, then variables that would normally ask a question, will | |
272 | instead create ``fields'' in the buffer. A field-editing layer | |
273 | provides simple interaction through the fields. Typing in a field | |
274 | will cause all variable locations that are the same to edit at the | |
275 | same time. Pressing TAB on a field will move you to the next field. | |
276 | ||
277 | @node SRecode Minor Mode | |
278 | @chapter SRecode Minor Mode | |
279 | ||
280 | The Semantic Recode minor mode enables a keymap and menu that provides | |
281 | simple access to different templates or template applications. | |
282 | ||
283 | The key prefix is @key{C-c /}. | |
284 | ||
285 | If the variable @code{srecode-takeover-INS-key} is set, then the key | |
286 | @key{<insert>} can also be used. | |
287 | ||
288 | The most important key is bound to @code{srecode-insert} which is | |
289 | @key{C-c / /}, or @key{insert insert}. @ref{Quick Start}. | |
290 | ||
291 | Major keybindings are: | |
292 | ||
293 | @table @key | |
294 | @item C-c / / | |
295 | Insert a template whose name is typed into the minibuffer. | |
296 | @item C-c / <lower case letter> | |
297 | Reserved for direct binding of simple templates to keys using a | |
298 | keybinding command in the template file. | |
299 | @item C-c / <upper case letter> | |
300 | Reserved for template applications (Such as comment or get/set inserter.) | |
301 | @item C-c / E | |
302 | Edit the code of a template. | |
303 | @item C-c / . | |
304 | Insert template again. This will cause the previously inserted | |
305 | template to be inserted again. | |
306 | @end table | |
307 | ||
308 | @section Field Editing | |
309 | ||
310 | By default, when inserting a template, if the user needs to enter text | |
311 | to fill in a part of the template, then the minibuffer is used to | |
cccaebd2 | 312 | query for that information. SRecode also supports a field-editing mode |
ac1d9dde EL |
313 | that can be used instead. To enable it set: |
314 | ||
315 | @defun srecode-insert-ask-variable-method | |
316 | @anchor{srecode-insert-ask-variable-method} | |
317 | Determine how to ask for a dictionary value when inserting a template. | |
318 | Only the @var{ASK} style inserter will query the user for a value. | |
319 | Dictionary value references that ask begin with the ? character. | |
320 | Possible values are: | |
321 | @table @code | |
322 | @item ask | |
323 | Prompt in the minibuffer as the value is inserted. | |
324 | @item field | |
325 | Use the dictionary macro name as the inserted value, | |
326 | and place a field there. Matched fields change together. | |
327 | @end table | |
328 | ||
329 | @b{NOTE}: The field feature does not yet work with XEmacs. | |
330 | @end defun | |
331 | ||
332 | Field editing mode is supported in newer versions of Emacs. You | |
333 | will not be prompted to fill in values while the template is | |
334 | inserted. Instead, short regions will be highlighted, and the cursor | |
335 | placed in a field. Typing in the field will then fill in the value. | |
336 | Several fields might be linked together. In that case, typing in one | |
337 | area will modify the other linked areas. Pressing TAB will move | |
338 | between editable fields in the template. | |
339 | ||
340 | Once the cursor moves out of the are inserted by the template, all the | |
341 | fields are cancelled. | |
342 | ||
343 | @b{NOTE}: Some conveniences in templates, such as completion, or | |
cccaebd2 | 344 | character restrictions are lost when using field editing mode. |
ac1d9dde EL |
345 | |
346 | @node Template Writing | |
347 | @chapter Template Writing | |
348 | @anchor{@code{SRecode-template-mode}} | |
349 | ||
350 | @code{srecode-template-mode} is the major mode used for designing new | |
351 | templates. @srecode{} files (Extension @file{.srt}) are made up of | |
352 | variable settings and template declarations. | |
353 | ||
354 | Here is an overview of the terminology you will need for the next few | |
355 | sections: | |
356 | ||
357 | @table @asis | |
358 | @item template file | |
359 | A file with a @file{.srt} extension which contains settings, | |
360 | variables, and templates. | |
361 | @item template | |
362 | One named entity which represents a block of text that will be | |
363 | inserted. The text is compiled into a sequence of insertable | |
364 | entities. The entities are string constants, and macros. | |
365 | @item macro | |
366 | A macro is a text sequence within template text that is replaced with | |
367 | some other value. | |
368 | @item dictionary | |
369 | A table of variable names and values. | |
370 | @item subdictionary | |
371 | A dictionary that is subordinate under another dictionary as a value | |
372 | to some variable. | |
373 | @item variable | |
374 | A variable is an entry in a dictionary which has a value. | |
375 | @end table | |
376 | ||
377 | @menu | |
378 | * Variables:: Creating special and regular variables. | |
379 | * Templates:: Creating templates | |
380 | * Contexts:: Templates are grouped by context | |
381 | * Prompts:: Setting prompts for interactive insert macros | |
382 | @end menu | |
383 | ||
384 | @node Variables | |
385 | @section Variables | |
386 | ||
387 | Variables can be set up and used in templates. Many variables you may | |
388 | use are set up via template arguments, but some may be preferences a | |
389 | user can set up that are used in system templates. | |
390 | ||
391 | When expanding a template, variables are stored in a @dfn{dictionary}. | |
392 | Dictionary entries are variables. Variables defined in templates can | |
393 | have string like values. | |
394 | ||
395 | A variable can be set like this: | |
396 | @example | |
397 | set VARNAME "some value" | |
398 | @end example | |
399 | ||
400 | Note that a VARIABLE is a name in a dictionary that can be used in a | |
cccaebd2 | 401 | MACRO in a template. The macro references some variable by name. |
ac1d9dde EL |
402 | |
403 | @menu | |
404 | * String Values:: Basic Variable values | |
405 | * Multi-string Values:: Complex variable values | |
406 | * Section Show:: Enabling the display of a named section. | |
407 | * Special Variables:: Variables with special names | |
408 | * Automatic Loop Variables:: Variables automatically set in section loops. | |
409 | * Compound Variable Values:: Compound Variable Values | |
410 | @end menu | |
411 | ||
412 | @node String Values | |
413 | @subsection String Values | |
414 | ||
415 | Variables can be set to strings. Strings may contain newlines or any | |
416 | other characters. Strings are interpreted by the Emacs Lisp reader so | |
417 | @code{\n}, @code{\t}, and @code{\"} work. | |
418 | ||
419 | When a string is inserted as part of a template, nothing within the | |
cccaebd2 | 420 | string is interpreted, such as template escape characters. |
ac1d9dde EL |
421 | |
422 | @node Multi-string Values | |
423 | @subsection Multi-string Values | |
424 | ||
425 | A variable can be set to multiple strings. A compound value is | |
426 | usually used when you want to use dictionary entries as part of a | |
427 | variable later on. | |
428 | ||
429 | Multi-string variable values are set like string values except there | |
430 | are more than one. For example | |
431 | ||
432 | @example | |
433 | set NAME "this" "-mode" | |
434 | @end example | |
435 | ||
436 | These two strings will be concatenated together. | |
437 | ||
438 | A more useful thing is to include dictionary variables and concatenate | |
439 | those into the string. Use the ``macro'' keyword to include the name | |
440 | of a variable. This is like macros in a template. For example: | |
441 | ||
442 | @example | |
443 | set NAME macro "MODE" "-mode" | |
444 | @end example | |
445 | ||
446 | will extract the value of the dictionary variable MODE and append | |
447 | ``-mode'' to the end. | |
448 | ||
449 | @node Section Show | |
450 | @subsection Section Show | |
451 | ||
452 | To set a variable to show a template section, use the @code{show} | |
453 | command. Sections are blocks of a template wrapped in section macros. | |
454 | If there is a section macro using @var{NAME} it will be shown for each | |
455 | dictionary associated with the @var{NAME} macro. | |
456 | ||
457 | @example | |
458 | show NAME | |
459 | @end example | |
460 | ||
461 | This will enable that section. | |
462 | ||
463 | ||
f99f1641 | 464 | NOTE: May 11, 2008: I haven't used this yet, so I don't know if it works. |
ac1d9dde EL |
465 | |
466 | ||
467 | @node Special Variables | |
468 | @subsection Special Variables | |
469 | ||
470 | Some variables have special meaning that changes attributes when | |
471 | templates are compiled, including: | |
472 | ||
473 | @table @code | |
474 | @item escape-start | |
475 | This is the character sequence that escapes from raw text to template | |
476 | macro names. The ability to change the escape characters are key for | |
477 | enabling @srecode{} templates to work across many kinds of languages. | |
478 | @item escape-end | |
479 | This is the character sequence that escapes the end of a template | |
480 | macro name. | |
481 | ||
482 | Example: | |
483 | @example | |
484 | set escape_start "$" | |
485 | set escape_end "$" | |
486 | @end example | |
487 | @item mode | |
488 | This is the major mode, as a string with the full Emacs Lisp symbol in | |
489 | it. All templates in this file will be installed into the template | |
490 | table for this major mode. | |
491 | ||
492 | Multiple template files can use the same mode, and all those templates | |
493 | will be available in buffers of that mode. | |
494 | ||
495 | Example: | |
496 | @example | |
497 | set mode "emacs-lisp-mode" | |
498 | @end example | |
499 | ||
500 | @item priority | |
501 | The priority of a file is a number in a string constant that | |
502 | indicates where it lies in the template search order. System | |
503 | templates default to low priority numbers. User templates default to | |
504 | high priority numbers. You can specify the priority of your template | |
505 | to insert it anywhere in the template search list. | |
506 | ||
507 | If there are multiple templates with the same context and name, the | |
508 | template with the highest priority number will be used. | |
509 | ||
510 | If multiple files have the same priority, then then sort order is | |
511 | unpredictable. If no template names match, then it doesn't matter. | |
512 | ||
513 | Example: | |
514 | @example | |
515 | set priority "35" | |
516 | @end example | |
517 | ||
518 | @item application | |
519 | If a template file contains templates only needed for a particular | |
520 | application, then specify an application. Template files for an | |
521 | application are stored in the template repository, but are not used in | |
522 | the generic template insertion case. | |
523 | ||
524 | The application with a particular name will access these templates | |
525 | from Lisp code. | |
526 | ||
527 | Example: | |
528 | @example | |
529 | set application "document" | |
530 | @end example | |
531 | ||
532 | @item project | |
533 | If a template file contains templates, or template overrides specific | |
534 | to a set of files under a particular directory, then that template | |
535 | file can specify a ``project'' that it belongs to. | |
536 | ||
537 | Set the ``project'' special variable to a directory name. Only files | |
538 | under that directory will be able to access the templates in that | |
539 | file. | |
540 | ||
541 | Any template file that has a project specified will get have a | |
542 | priority that is set between SRecode base templates, and user defined | |
543 | templates. | |
544 | ||
cccaebd2 | 545 | Templates can be compiled via a project system, such as EDE@. EDE |
ac1d9dde EL |
546 | loaded templates will get a @var{project} set automatically. |
547 | ||
548 | Example: | |
549 | @example | |
550 | set project "/tmp/testproject" | |
551 | @end example | |
552 | ||
553 | @end table | |
554 | ||
555 | If you need to insert the characters that belong to the variables | |
556 | @code{escape_start} or @code{escape_end}, then place those into | |
557 | a variable. For example | |
558 | ||
559 | @example | |
560 | set escape_start "$" | |
561 | set escape_end "$" | |
562 | set DOLLAR "$" | |
563 | @end example | |
564 | ||
565 | @node Automatic Loop Variables | |
566 | @subsection Automatic Loop Variables | |
567 | ||
568 | When section macros are used, that section is repeated for each | |
569 | subdictionary bound to the loop variable. | |
570 | ||
571 | Each dictionary added will automatically get values for positional | |
572 | macros which will enable different @var{sections}. The automatic | |
573 | section variables are. | |
574 | ||
575 | @itemize @bullet | |
f99f1641 PE |
576 | @item @var{first}---The first entry in the table. |
577 | @item @var{notfirst}---Not the first entry in the table. | |
578 | @item @var{last}---The last entry in the table | |
579 | @item @var{notlast}---Not the last entry in the table. | |
ac1d9dde EL |
580 | @end itemize |
581 | ||
582 | @node Compound Variable Values | |
583 | @subsection Compound Variable Values | |
584 | ||
585 | A variable can also have a compound value. This means the value of | |
586 | the variable is an @EIEIO{} object, which is a subclass of | |
587 | @code{srecode-dictionary-compound-value}. | |
588 | ||
589 | New compound variables can only be setup from Lisp code. See | |
590 | @ref{Compound Dictionary Values} for details on setting up compound | |
591 | variables from Lisp. | |
592 | ||
593 | @node Templates | |
594 | @section Templates | |
595 | ||
596 | A template represents a text pattern that can be inserted into | |
597 | a buffer. | |
598 | ||
cccaebd2 | 599 | A basic template is declared like this: |
ac1d9dde EL |
600 | |
601 | @example | |
602 | template TEMPLATENAME :arg1 :arg2 | |
603 | "Optional documentation string" | |
604 | ---- | |
605 | The text to your template goes here. | |
606 | ---- | |
607 | bind "a" | |
608 | @end example | |
609 | ||
610 | Templates are stored in a template table by name, and are inserted by | |
611 | the @var{templatename} provided. | |
612 | ||
613 | The documentation string is optional. This documentation string will | |
614 | be used to aid users in selecting which template they want to use. | |
615 | ||
616 | The code that makes up the raw template occurs between the lines that | |
617 | contain the text "-----". | |
618 | ||
619 | @menu | |
620 | * Template Section Dictionaries:: Template Scoped Macro values | |
cccaebd2 | 621 | * Template Macros:: Macros occurring in template patterns |
ac1d9dde EL |
622 | @end menu |
623 | ||
624 | @node Template Section Dictionaries | |
625 | @subsection Template Section Dictionaries | |
626 | ||
627 | To add variable values to section dictionaries used within a specific | |
628 | template, you can add them to the beginning of the template | |
629 | declaration like this: | |
630 | ||
631 | @example | |
632 | template TEMPLATENAME :arg1 :arg2 | |
633 | "Optional documentation string" | |
634 | sectiondictionary "A" | |
635 | set NAME "foo" | |
636 | ---- | |
637 | A beginning line @{@{NAME@}@} | |
638 | @{@{#A@}@}Optional string @{@{NAME@}@} here@{@{/A@}@} | |
639 | An end line | |
640 | ---- | |
641 | @end example | |
642 | ||
643 | In this example, the @var{NAME} variable gets the value ``foo'', but | |
cccaebd2 | 644 | only while it is inside section macro A@. The outer scoped NAME will |
ac1d9dde EL |
645 | be empty. |
646 | ||
647 | This is particularly useful while using an include macro to pull in a | |
648 | second template. In this way, you can pass values known from one | |
649 | template to a subordinate template where some value is not known. | |
650 | ||
651 | From the Emacs Lisp default template file, a syntax table is just a | |
652 | variable with a specialized value. | |
653 | ||
654 | If a variable is declared like this (where $ is the escape character): | |
655 | ||
656 | @example | |
657 | template variable :el | |
658 | "Insert a variable. | |
659 | DOC is optional." | |
660 | ---- | |
661 | (defvar $?NAME$ $^$ | |
662 | "$DOC$") | |
663 | ---- | |
664 | @end example | |
665 | ||
666 | then you can see that there is a NAME and DOC that is needed. | |
667 | The @code{^} point inserter is also a handy key here. | |
668 | ||
669 | The syntax table wants a variable, but knows the values of some of | |
670 | these variables, and can recast the problem like this by using | |
671 | template specific @code{sectiondictionary} macro declarations. | |
672 | ||
673 | @example | |
674 | template syntax-table | |
675 | "Create a syntax table." | |
676 | sectiondictionary "A" | |
677 | set NAME macro "?MODESYM" "-mode-syntax-table" | |
678 | set DOC "Syntax table used in " macro "?MODESYM" " buffers." | |
679 | ---- | |
680 | $<A:variable$ | |
681 | (let ((table (make-syntax-table (standard-syntax-table)))) | |
682 | (modify-syntax-entry ?\; ". 12" table) ;; SEMI, Comment start ;; | |
683 | ;; ... | |
684 | table) | |
685 | $/A$ | |
686 | ---- | |
687 | @end example | |
688 | ||
689 | In this way, @var{NAME} can be set as a user posed question for | |
690 | @var{MODESYM} with ``-mode-syntax-table'' appended. A simplified doc | |
691 | string will also be inserted. | |
692 | ||
693 | Lastly, the @var{A} section contains more macro text which is inserted | |
694 | at the @code{^} point marker. | |
695 | ||
696 | By creating useful base templates for things like function or variable | |
697 | declarations, and recycling them in higher-order templates, an end | |
698 | user can override the basic declarator, and the higher order templates | |
699 | will then obey the new format, or perhaps even work in more than one | |
700 | major mode. | |
701 | ||
702 | @node Template Macros | |
703 | @subsection Template Macros | |
704 | ||
705 | Template macros occur in the template text. The default escape | |
706 | characters are ``@{@{`` and ``@}@}'', though they can be changed | |
707 | in the top-level variables. See @ref{Variables}. | |
708 | ||
709 | Thus, if you have the template code that looks like this: | |
710 | ||
711 | @example | |
712 | ;; Author: @{@{AUTHOR@}@} | |
713 | @end example | |
714 | ||
715 | Then the text between @{@{ and @}@} are a macro, and substituted by | |
716 | the value of the variable @var{AUTHOR}. | |
717 | ||
718 | Macros can be specialized to be more than just a text string. For | |
719 | example, the macro above could be augmented with an Emacs Lisp | |
720 | function. | |
721 | ||
722 | @example | |
723 | ;; Author: @{@{AUTHOR:upcase@}@} | |
724 | @end example | |
725 | ||
726 | In this case, the Emacs Lisp function @code{upcase} will be called on | |
727 | the text value of the @var{AUTHOR} variable. | |
728 | ||
729 | Macros can also be specialized to have different behaviors by using a | |
730 | prefix, non-alpha character or symbol. For example: | |
731 | ||
732 | @example | |
733 | @{@{! This is a comment inside macro escape characters @}@} | |
734 | @end example | |
735 | ||
736 | shows that the ``!'' symbol is for comments. | |
737 | ||
738 | Alternately, a macro could query the user during insertion: | |
739 | ||
740 | @example | |
741 | (defun @{@{?NAME@}@} () | |
742 | @{@{^@}@} | |
743 | ) ;; End of @{@{NAME@}@} | |
744 | @end example | |
745 | ||
746 | the ``?'' symbol indicates that if the symbol @var{NAME} isn't in the | |
747 | dictionary, then the user should be queried for the @var{NAME} | |
748 | variable. If @var{NAME} appears again in the template, the original | |
749 | value specified by the user will be inserted again. | |
750 | ||
751 | If the text from a dictionary value is to be placed in column format, | |
752 | you can use the ``|'' symbol to indicate you want column control. For | |
753 | example: | |
754 | ||
755 | @example | |
756 | | this | that |@{@{#A@}@} | |
757 | | @{@{|THIS:4@}@} | @{@{|THAT:4@}@} |@{@{/A@}@} | |
758 | @end example | |
759 | ||
760 | For each repeated section ``#A'' the dictionary values for @var{THIS} | |
761 | and @var{THAT} will be inserted and either trimmed to, or expanded to | |
762 | 4 characters in width. | |
763 | ||
764 | Macros that are prefixed with the ``#'' symbol denote a section. A | |
765 | macro of the same name with a ``/'' prefix denotes the end of that | |
766 | section. | |
767 | ||
768 | @example | |
769 | @{@{#MOOSE@}@} | |
770 | Here is some text describing moose. | |
771 | @{@{/MOOSE@}@} | |
772 | @end example | |
773 | ||
774 | In this example if the section MOOSE was ``shown'' in the active | |
775 | dictionary, then the text between the # and / macros will also be | |
776 | inserted. | |
777 | ||
778 | All the text and macros within a section are either not shown at all | |
779 | (if that section is not 'visible') or the section is shown one time | |
780 | for each dictionary added to that symbol. | |
781 | @xref{Developing Template Functions}. | |
ac1d9dde EL |
782 | |
783 | Macros prefixed with ``>'' will include another template. Include | |
784 | macros would look like this: | |
785 | ||
786 | @example | |
787 | @{@{>FOO:defun@}@} | |
788 | @end example | |
789 | ||
790 | where @code{FOO} is the dictionary variable for the sub-dictionary used for | |
791 | expanding the template @code{defun}. The @code{defun} template will | |
792 | be looked up in the template repository for the current mode, or in | |
793 | any inherited modes. | |
794 | ||
795 | Another way to include another template is with an include macro that | |
796 | will also wrap section text. The includewrap insertion method looks | |
797 | like this: | |
798 | ||
799 | @example | |
800 | @{@{<FOO:defun@}@}Handy Text goes here@{@{/FOO@}@} | |
801 | @end example | |
802 | ||
803 | In this case, @code{defun} is included just as above. If the | |
804 | @code{defun} template has a @{@{^@}@} macro in it, then the | |
805 | section text ``Handy Text goes here'' will be inserted at that point, | |
806 | and that location will not be saved as the cursor location. | |
807 | ||
808 | If there is no @{@{^@}@}, then the text will not be inserted. | |
809 | ||
810 | For both kinds of include macros, you may need to include a template | |
811 | from a different context. You can use @code{:} separate the context | |
812 | from the name, like this: | |
813 | ||
814 | @example | |
815 | @{@{>FOO:declaration:function@}@} | |
816 | @end example | |
817 | ||
818 | @node Contexts | |
819 | @section Context | |
820 | ||
821 | Each template belongs to a context. When promting for a template by | |
822 | name, such as with @kbd{C-c / /}, the name is prefixed by the current | |
823 | context. If there is no context, it defaults to @code{declaration}. | |
824 | ||
825 | You can change context like this: | |
826 | ||
827 | @example | |
828 | context NAME | |
829 | @end example | |
830 | ||
831 | where @var{name} is some symbol that represents any context. | |
832 | ||
833 | A context resides over all templates that come after it until the next | |
834 | context statement. Thus: | |
835 | ||
836 | @example | |
837 | context C1 | |
838 | ||
839 | template foo | |
840 | "Foo template in C1" | |
841 | ---- | |
842 | ---- | |
843 | ||
844 | context C2 | |
845 | ||
cccaebd2 | 846 | template foo |
ac1d9dde EL |
847 | "Foo template in C2" |
848 | ---- | |
849 | ---- | |
850 | @end example | |
851 | ||
852 | creates two @code{foo} templates. The first one is when in context | |
853 | C1. The second is available in context C2. | |
854 | ||
855 | This is useful if there are multiple ways to declare something like a | |
856 | function or variable that differ only by where it is in the syntax of | |
cccaebd2 | 857 | the language. The name @code{foo} is not ambiguous because each is in |
ac1d9dde EL |
858 | a different context. |
859 | ||
860 | @node Prompts | |
861 | @section Prompt | |
862 | ||
cccaebd2 | 863 | Some templates use prompting macro insertion. A macro that needs a |
ac1d9dde EL |
864 | prompt looks like this: |
865 | ||
866 | @example | |
867 | @{@{?NAME@}@} | |
868 | @end example | |
869 | ||
870 | where ? comes after the first escape character. | |
871 | ||
872 | by default, it will use a prompt like this when it is encountered: | |
873 | ||
874 | @example | |
875 | Specify NAME: | |
876 | @end example | |
877 | ||
878 | For such macros, you can pre-define prompts for any dictionary entry. | |
879 | When that dictionary entry is first encountered, the user is prompted, | |
cccaebd2 | 880 | and subsequent occurrences of that dictionary entry use the same value. |
ac1d9dde EL |
881 | |
882 | To get a different prompt, use a prompt command like this: | |
883 | ||
884 | @example | |
885 | prompt VARNAME "Nice Way to ask for VARNAME: " | |
886 | @end example | |
887 | ||
888 | Now, if you put this in a template: | |
889 | ||
890 | @example | |
891 | template variable | |
892 | ---- | |
893 | (defvar @{@{?VARNAME@}@} nil | |
894 | "") | |
895 | ---- | |
896 | @end example | |
897 | ||
898 | when VARNAME is encountered, it will use the nice prompt. | |
899 | ||
900 | Prompts can be extended as well. For example: | |
901 | ||
902 | @example | |
903 | prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p | |
904 | @end example | |
905 | ||
906 | In this case, the @code{default} keyword indicates that | |
907 | @code{"srecode"} is the default string to use, and @code{y-or-n-p} is | |
908 | the function to use to ask the question. | |
909 | ||
910 | For @code{y-or-n-p} if you type ``y'' it inserts the default string, | |
911 | otherwise it inserts empty. | |
912 | ||
913 | For any other symbol that occurs after the @code{read} token, it is | |
914 | expected to take the same argument list as @code{read-string}. As | |
915 | such, you can create your own prompts that do completing reads on | |
916 | deterministic values. | |
917 | ||
918 | To have the default be calculated later from a dictionary entry, you | |
919 | need to use the @code{defaultmacro} keyword instead. | |
920 | ||
921 | @example | |
922 | prompt VARNAME "Varname: " defaultmacro "PREFIX" | |
923 | @end example | |
924 | ||
cccaebd2 | 925 | now, when it attempts to read in VARNAME, it will pre-populate the text |
ac1d9dde EL |
926 | editing section with whatever the value of PREFIX is. |
927 | ||
928 | Some language arguments may supply possible prefixes for prompts. | |
929 | Look for these when creating your prompts. | |
930 | ||
931 | @node Dictionaries | |
932 | @chapter Dictionaries | |
933 | ||
934 | Dictionaries are a set of variables. The values associated with the | |
935 | variable names could be anything, but how it is handled is dependent | |
936 | on the type of macro being inserted. | |
937 | ||
938 | Most of this chapter is for writing Lisp programs that use @srecode{}. | |
939 | If you only want to write template files, then you only need to read | |
940 | the @ref{Template Argument Dictionary Entries} section. | |
941 | ||
942 | @menu | |
943 | * Create a Dictionary:: | |
944 | * Setting Dictionary Values:: Basic dictionary values | |
945 | * Compound Dictionary Values:: Complex dictionary values | |
946 | * Argument Resolution:: Automatic template argument resolution | |
947 | * Creating new Arguments:: Create new arguments for use in templates | |
948 | * Querying a Dictionary:: Querying a dictionary for values. | |
949 | * Template Argument Dictionary Entries:: Catalog of arguments | |
950 | @end menu | |
951 | ||
952 | @node Create a Dictionary | |
953 | @section Create a Dictionary | |
954 | ||
955 | @defun srecode-create-dictionary &optional buffer | |
956 | @anchor{srecode-create-dictionary} | |
957 | Create a dictionary for @var{buffer}. | |
958 | If @var{buffer} is not specified, use the current buffer. | |
959 | The dictionary is initialized with no variables or enabled sections. | |
960 | Any variables defined with @code{set} in the template, however, | |
961 | becomes a name in the dictionary. | |
962 | @end defun | |
963 | ||
964 | @node Setting Dictionary Values | |
965 | @section Setting Dictionary Values | |
966 | ||
967 | When building an @srecode{} based application, you will need to setup | |
968 | your dictionary values yourself. There are several utility functions | |
969 | for this. | |
970 | ||
cccaebd2 | 971 | In the simplest form, you can associate a string with a variable. |
ac1d9dde EL |
972 | |
973 | @defun srecode-dictionary-set-value dict name value | |
974 | @anchor{srecode-dictionary-set-value} | |
975 | In dictionary @var{dict}, set @var{name} to have @var{value}. | |
976 | @end defun | |
977 | ||
978 | For section macros, you can have alternate values. A section can | |
979 | either be toggled as visible, or it can act as a loop. | |
980 | ||
981 | @defun srecode-dictionary-show-section dict name | |
982 | @anchor{srecode-dictionary-show-section} | |
983 | In dictionary @var{dict}, indicate that the section @var{name} should be exposed. | |
984 | @end defun | |
985 | ||
986 | ||
987 | @defun srecode-dictionary-add-section-dictionary dict name show-only | |
988 | @anchor{srecode-dictionary-add-section-dictionary} | |
989 | In dictionary @var{DICT}, add a section dictionary for section macro @var{NAME}. | |
990 | Return the new dictionary. | |
991 | ||
992 | You can add several dictionaries to the same section entry. | |
993 | For each dictionary added to a variable, the block of codes in | |
994 | the template will be repeated. | |
995 | ||
cccaebd2 PE |
996 | If optional argument @var{SHOW-ONLY} is non-@code{nil}, then don't add |
997 | a new dictionary if there is already one in place. Also, don't add | |
998 | @var{FIRST}/@var{LAST} entries. | |
ac1d9dde EL |
999 | These entries are not needed when we are just showing a section. |
1000 | ||
1001 | Each dictionary added will automatically get values for positional macros | |
1002 | which will enable @var{SECTIONS} to be enabled. | |
1003 | ||
1004 | @table @var | |
1005 | @item first | |
1006 | The first entry in the table. | |
1007 | @item notfirst | |
1008 | Not the first entry in the table. | |
1009 | @item last | |
1010 | The last entry in the table | |
1011 | @item notlast | |
1012 | Not the last entry in the table. | |
1013 | @end table | |
1014 | ||
1015 | Adding a new dictionary will alter these values in previously | |
1016 | inserted dictionaries. | |
1017 | @end defun | |
1018 | ||
1019 | @node Compound Dictionary Values | |
1020 | @section Compound Dictionary Values | |
1021 | ||
1022 | If you want to associate a non-string value with a dictionary | |
1023 | variable, then you will need to use a compound value. Compound | |
1024 | dictionary values are derived using @EIEIO{} from a base class for | |
1025 | handling arbitrary data in a macro. | |
1026 | ||
1027 | @deffn Type srecode-dictionary-compound-value | |
1028 | @anchor{srecode-dictionary-compound-value} | |
1029 | A compound dictionary value. | |
1030 | Values stored in a dictionary must be a @var{string}, | |
1031 | a dictionary for showing sections, or an instance of a subclass | |
1032 | of this class. | |
1033 | ||
1034 | Compound dictionary values derive from this class, and must | |
1035 | provide a sequence of method implementations to convert into | |
1036 | a string. | |
1037 | @end deffn | |
1038 | ||
1039 | Your new subclass of the compound value needs to implement these | |
1040 | methods: | |
1041 | ||
1042 | @defun srecode-compound-toString cp function dictionary | |
1043 | @anchor{srecode-compound-toString} | |
1044 | Convert the compound dictionary value @var{cp} to a string. | |
1045 | If @var{function} is non-@code{nil}, then @var{function} is somehow applied to an aspect | |
1046 | of the compound value. The @var{function} could be a fraction | |
1047 | of some function symbol with a logical prefix excluded. | |
1048 | @end defun | |
1049 | ||
1050 | The next method is for dumping out tables during debugging. | |
1051 | ||
1052 | @defun srecode-dump cp &optional indent | |
1053 | @anchor{srecode-dump} | |
1054 | Display information about this compound value. | |
1055 | @end defun | |
1056 | ||
1057 | ||
1058 | Here is an example of wrapping a semantic tag in a compound value: | |
1059 | ||
1060 | @example | |
1061 | (defclass srecode-semantic-tag (srecode-dictionary-compound-value) | |
1062 | ((prime :initarg :prime | |
1063 | :type semantic-tag | |
1064 | :documentation | |
1065 | "This is the primary insertion tag.") | |
1066 | ) | |
1067 | "Wrap up a collection of semantic tag information. | |
1068 | This class will be used to derive dictionary values.") | |
1069 | ||
1070 | (defmethod srecode-compound-toString((cp srecode-semantic-tag) | |
1071 | function | |
1072 | dictionary) | |
1073 | "Convert the compound dictionary value CP to a string. | |
1074 | If FUNCTION is non-nil, then FUNCTION is somehow applied to an | |
1075 | aspect of the compound value." | |
1076 | (if (not function) | |
1077 | ;; Just format it in some handy dandy way. | |
1078 | (semantic-format-tag-prototype (oref cp :prime)) | |
1079 | ;; Otherwise, apply the function to the tag itself. | |
1080 | (funcall function (oref cp :prime)) | |
1081 | )) | |
1082 | @end example | |
1083 | ||
1084 | @node Argument Resolution | |
1085 | @section Argument Resolution | |
1086 | ||
1087 | Some dictionary entries can be set via template arguments in the | |
1088 | template declaration. For examples of template arguments, see | |
1089 | @ref{Template Argument Dictionary Entries}. | |
1090 | ||
1091 | You can resolve an argument list into a dictionary with: | |
1092 | ||
1093 | @defun srecode-resolve-arguments temp dict | |
1094 | @anchor{srecode-resolve-arguments} | |
1095 | Resolve all the arguments needed by the template @var{temp}. | |
1096 | Apply anything learned to the dictionary @var{dict}. | |
1097 | @end defun | |
1098 | ||
1099 | @node Creating new Arguments | |
1100 | @section Creating new Arguments | |
1101 | ||
1102 | You can create new arguments for use in template files by writing new | |
1103 | Emacs Lisp functions. Doing so is easy. Here is an example for the | |
1104 | @code{:user} argument: | |
1105 | ||
1106 | @example | |
1107 | (defun srecode-semantic-handle-:user (dict) | |
1108 | "Add macros into the dictionary DICT based on the current :user." | |
1109 | (srecode-dictionary-set-value dict "AUTHOR" (user-full-name)) | |
1110 | (srecode-dictionary-set-value dict "LOGIN" (user-login-name)) | |
1111 | ;; ... | |
1112 | ) | |
1113 | @end example | |
1114 | ||
1115 | In this case, a function with the name prefix | |
1116 | @code{srecode-semantic-handle-} that ends in @code{:user} creates a | |
1117 | new argument @code{:user} that can be used in a template. | |
1118 | ||
1119 | Your argument handler must take one argument @var{dict}, which is the | |
1120 | dictionary to fill in. Inside your function, you can do whatever you | |
1121 | want, but adding dictionary values is the right thing. | |
1122 | ||
1123 | @node Querying a Dictionary | |
1124 | @section Querying a Dictionary | |
1125 | ||
cccaebd2 | 1126 | When creating a new argument, it may be useful to ask the dictionary |
ac1d9dde EL |
1127 | what entries are already set there, and conditionally create new |
1128 | entries based on those. | |
1129 | ||
1130 | In this way, a template author can get additional logic through more | |
1131 | advanced arguments. | |
1132 | ||
1133 | @defun srecode-dictionary-lookup-name dict name | |
1134 | @anchor{srecode-dictionary-lookup-name} | |
1135 | Return information about the current @var{DICT}'s value for @var{NAME}. | |
1136 | @var{DICT} is a dictionary, and @var{NAME} is a string that is the name of | |
1137 | a symbol in the dictionary. | |
1138 | This function derives values for some special NAMEs, such as @var{FIRST} | |
1139 | and '@var{LAST}'. | |
1140 | @end defun | |
1141 | ||
1142 | ||
1143 | ||
1144 | @node Template Argument Dictionary Entries | |
1145 | @section Template Argument Dictionary Entries | |
1146 | ||
1147 | When a dictionary is initialized for a template, then the dictionary | |
1148 | will be initialized with a predefined set of macro values. | |
1149 | ||
1150 | A template of the form: | |
1151 | ||
1152 | @example | |
1153 | template template-name :arg1 :arg2 | |
1154 | ---- | |
1155 | Your template goes here | |
1156 | ---- | |
1157 | @end example | |
1158 | ||
1159 | specifies two arguments :arg1, and :arg2. | |
1160 | ||
1161 | The following built-in simple arguments are available: | |
1162 | ||
1163 | @menu | |
1164 | * Base Arguments:: | |
1165 | * Semantic Arguments:: | |
1166 | * Language Arguments:: | |
1167 | @end menu | |
1168 | ||
1169 | @node Base Arguments | |
1170 | @subsection Base Arguments | |
1171 | ||
1172 | @subsubsection Argument :indent | |
1173 | ||
1174 | Supplies the @code{INDENT} macro. When @code{INDENT} is non-nil, then | |
1175 | each line is individually indented with | |
1176 | @code{indent-according-to-mode} during macro processing. | |
1177 | ||
1178 | @subsubsection Argument :blank | |
1179 | ||
1180 | Specifying this argument adds a special @code{:blank} handler at the | |
1181 | beginning and end of the template. This handler will insert @code{\n} | |
1182 | if the insertion point is not on a line by itself. | |
1183 | ||
1184 | @subsubsection Argument :region | |
1185 | ||
1186 | If there is an active region via @code{transient-mark-mode}, or | |
1187 | @code{mouse-drag-region}, then the @code{REGION} section will be | |
1188 | enabled. | |
1189 | ||
1190 | In addition, @code{REGIONTEXT} will be set the the text in the region, | |
1191 | and that region of text will be ``killed'' from the current buffer. | |
1192 | ||
1193 | If standard-output is NOT the current buffer, then the region will not | |
1194 | be deleted. In this way, you can safely use @code{:region} using | |
1195 | templates in arbitrary output streams. | |
1196 | ||
1197 | @subsubsection Argument :user | |
1198 | ||
1199 | Sets up variables about the current user. | |
1200 | ||
1201 | @table @code | |
1202 | @item AUTHOR | |
1203 | Value of the Emacs function @code{user-full-name} | |
1204 | @item EMAIL | |
1205 | Current Emacs user's email address. | |
1206 | @item LOGIN | |
1207 | Current Emacs user's login name. | |
1208 | @item UID | |
1209 | Current Emacs user's login ID. | |
1210 | @item EMACSINITFILE | |
1211 | This Emacs sessions' init file. | |
1212 | @end table | |
1213 | ||
1214 | @subsubsection Argument :time | |
1215 | ||
1216 | Sets up variables with the current date and time. | |
1217 | ||
1218 | @table @code | |
1219 | @item YEAR | |
1220 | The current year. | |
1221 | @item MONTH | |
1222 | The current month as a number. | |
1223 | @item MONTHNAME | |
1224 | The current month name, unabbreviated. | |
1225 | @item DAY | |
1226 | The current day as a number. | |
1227 | @item WEEKDAY | |
1228 | The current day of the week as an abbreviated name | |
1229 | @item HOUR | |
1230 | The current hour in 24 hour format. | |
1231 | @item HOUR12 | |
1232 | The current hour in 12 hour format. | |
1233 | @item AMPM | |
cccaebd2 | 1234 | Locale equivalent of AM or PM@. Useful with HOUR12. |
ac1d9dde EL |
1235 | @item MINUTE |
1236 | The current minute. | |
1237 | @item SECOND | |
1238 | The current second. | |
1239 | @item TIMEZONE | |
1240 | The timezone string. | |
1241 | @item DATE | |
1242 | The Locale supported date (%D). | |
1243 | @item TIME | |
1244 | The Locale supported time format (%X). | |
1245 | @end table | |
1246 | ||
1247 | @subsubsection Argument :file | |
1248 | ||
1249 | Sets up variables with details about the current file. | |
1250 | ||
1251 | @table @code | |
1252 | @item FILENAME | |
1253 | The filename without the directory part of the current buffer. | |
1254 | @item FILE | |
1255 | The filename without the directory or extension | |
1256 | @item EXTENSION | |
1257 | The filename extension. | |
1258 | @item DIRECTORY | |
1259 | The directory in which the current buffer resides. | |
1260 | @item MODE | |
1261 | Major mode of this buffer. | |
1262 | @item SHORTMODE | |
1263 | Major mode of this buffer without ``-mode''. | |
1264 | Useful for inserting the Emacs mode specifier. | |
1265 | @item section RCS | |
1266 | Show the section RCS if there is a CVS or RCS directory here. | |
1267 | @end table | |
1268 | ||
1269 | @subsubsection Argument :system | |
1270 | ||
1271 | Sets up variables with computer system information. | |
1272 | ||
1273 | @table @code | |
1274 | @item SYSTEMCONF | |
1275 | The ``system-configuration''. | |
1276 | @item SYSTEMTYPE | |
1277 | The ``system-type''. | |
1278 | @item SYSTEMNAME | |
1279 | The ``system-name''. | |
1280 | @item MAILHOST | |
1281 | The name of the machine Emacs derived mail ``comes from''. | |
1282 | @end table | |
1283 | ||
1284 | @subsubsection Argument :kill | |
1285 | ||
1286 | @table @code | |
1287 | @item KILL | |
1288 | The top-most item from the kill ring. | |
1289 | @item KILL2 | |
1290 | The second item in the kill ring. | |
1291 | @item KILL3 | |
1292 | The third item in the kill ring. | |
1293 | @item KILL4 | |
1294 | The fourth item in the kill ring. | |
1295 | @end table | |
1296 | ||
1297 | @node Semantic Arguments | |
1298 | @subsection Semantic Arguments | |
1299 | ||
1300 | @subsubsection Argument :tag | |
1301 | ||
1302 | The :tag argument is filled in with information from Semantic. | |
1303 | The tag in question is queried from the senator tag ring, or passed | |
1304 | in from @srecode{} utilities that use tags in templates. | |
1305 | ||
1306 | @table @code | |
1307 | @item TAG | |
1308 | This is a compound value for the tag in the current senator kill ring, | |
1309 | or something handled via the variable | |
1310 | @code{srecode-semantic-selected-tag}. | |
1311 | ||
1312 | @defvar srecode-semantic-selected-tag | |
1313 | @anchor{srecode-semantic-selected-tag} | |
1314 | The tag selected by a @code{:tag} template argument. | |
1315 | If this is @code{nil}, then @code{senator-tag-ring} is used. | |
1316 | @end defvar | |
1317 | ||
1318 | Use the function part of a macro insert to extract obscure parts | |
1319 | of the tag. | |
1320 | @item NAME | |
1321 | The name of the tag as a string. | |
1322 | @item TYPE | |
1323 | The data type of the tag as a string. | |
1324 | @end table | |
1325 | ||
1326 | If @var{tag} is a function, you will get these additional dictionary | |
1327 | entries. | |
1328 | ||
1329 | @table @code | |
1330 | @item ARGS | |
cccaebd2 | 1331 | A Loop macro value. Each argument is inserted in ARGS@. To create a |
ac1d9dde EL |
1332 | comma separated list of arguments, you might do this: |
1333 | ||
1334 | @example | |
1335 | @{@{#ARGS@}@}@{@{TYPE@}@} @{@{NAME@}@}@{@{#NOTLAST@}@},@{@{/NOTLAST@}@}@{@{/ARGS@}@} | |
1336 | @end example | |
1337 | ||
1338 | Within the section dictionaries for each argument, you will find both | |
1339 | @var{NAME} and @var{TYPE}, in addition to the automatic section values | |
1340 | for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}. | |
1341 | @item PARENT | |
1342 | The string name of the parent of this function, if the function is a | |
1343 | method of some class. | |
1344 | @item THROWS | |
1345 | In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified. | |
1346 | @end table | |
1347 | ||
1348 | If @var{tag} is a variable, you will get these dictionary entries. | |
1349 | ||
1350 | @table @code | |
1351 | @item DEFAULTVALUE | |
1352 | Enabled if there is a @var{VALUE}. | |
1353 | @item VALUE | |
1354 | An entry in the @var{HAVEDEFAULT} subdictionary that represents the | |
1355 | textual representation of the default value of this variable. | |
1356 | @end table | |
1357 | ||
1358 | If @var{tag} is a datatype, you will get these dictionary entries. | |
1359 | ||
1360 | @table @code | |
1361 | @item PARENTS | |
1362 | Section dictionaries for the parents of this class. Each parent will | |
1363 | have a @var{NAME}. | |
1364 | @item INTERFACES | |
1365 | Section dictionaries for all the implemented interfaces of this | |
1366 | class. Each interface will have a @var{NAME}. | |
1367 | @end table | |
1368 | ||
1369 | Note that data type templates should always have a @code{@{@{^@}@}} | |
1370 | macro in it where the core contents of that type will go. This is why | |
1371 | data types don't have subdictionaries full of the slots in the classes | |
1372 | or structs. | |
1373 | ||
1374 | @node Language Arguments | |
1375 | @subsection language Arguments | |
1376 | ||
1377 | Each language typically has its own argument. These arguments can be | |
1378 | used to fill in language specific values that will be useful. | |
1379 | ||
1380 | @subsubsection Argument :srt | |
1381 | ||
1382 | Used for SRecoder template files. | |
1383 | ||
1384 | @table @code | |
1385 | @item ESCAPE_START | |
1386 | The characters used for an escape start | |
1387 | @item ESCAPE_END | |
1388 | The characters used for an escape end | |
1389 | @end table | |
1390 | ||
1391 | @subsubsection Argument :cpp | |
1392 | ||
1393 | @table @code | |
1394 | @item HEADER | |
1395 | Shows this section if the current file is a header file. | |
1396 | @item NOTHEADER | |
1397 | The opposite of @code{HEADER}. | |
1398 | @item FILENAME_SYMBOL | |
1399 | The current filename reformatted as a C friendly symbol. | |
1400 | @end table | |
1401 | ||
1402 | @subsection Argument :java | |
1403 | ||
1404 | @table @code | |
1405 | @item FILENAME_AS_PACKAGE | |
1406 | Converts the filename into text that would be suitable as a package | |
1407 | name. | |
1408 | @item FILENAME_AS_CLASS | |
1409 | Converts the filename into text that would be suitable as a class-name | |
1410 | for the main class in the file. | |
1411 | @item CURRENT_PACKAGE | |
cccaebd2 | 1412 | Finds the occurrence of ``package'' and gets its value. |
ac1d9dde EL |
1413 | @end table |
1414 | ||
1415 | @subsubsection Argument :el | |
1416 | ||
1417 | Sets @code{PRENAME}. This would be a common prefix from all the | |
1418 | tags in the current buffer. | |
1419 | ||
1420 | Most Emacs Lisp packages have some common prefix used in a way similar | |
1421 | to namespaces in other languages. | |
1422 | ||
1423 | @subsubsection Argument :el-custom | |
1424 | ||
1425 | @table @code | |
1426 | @item GROUP | |
1427 | The name of the Emacs Custom group that instances of @code{defcustom} | |
1428 | ought to use. | |
1429 | @item FACEGROUP | |
cccaebd2 | 1430 | The name of the Emacs Custom group that faces declared with |
ac1d9dde EL |
1431 | @code{defface} ought to use. |
1432 | @end table | |
1433 | ||
1434 | @subsubsection Argument :texi | |
1435 | ||
1436 | @table @code | |
1437 | @item LEVEL | |
1438 | The current section level, such as @code{chapter} or @code{section}. | |
1439 | @item NEXTLEVEL | |
1440 | The next level down, so if @code{LEVEL} is @code{chapter}, then | |
1441 | @code{NEXTLEVEL} would be @code{section}. | |
1442 | @end table | |
1443 | ||
1444 | @subsubsection Argument :texitag | |
1445 | ||
1446 | The @code{:texitag} argument is like the @code{:tag} argument, except that | |
1447 | additional variable @code{TAGDOC} is provided for each tag. | |
1448 | ||
1449 | The @code{TAGDOC} is filled with derived documentation from the tag in | |
1450 | question, and that documentation is also reformatted to be mostly | |
1451 | texinfo compatible. | |
1452 | ||
1453 | @subsection Argument :android | |
1454 | ||
1455 | The @code{:android} argument pulls in information from your current | |
1456 | project. | |
1457 | ||
1458 | @@TODO - add more here. | |
1459 | ||
1460 | @node Developing Template Functions | |
1461 | @chapter Developing Template Functions | |
1462 | ||
1463 | You can develop your own custom template insertion functions. | |
1464 | Doing so is relatively simple, and requires that you write an Emacs | |
1465 | Lisp command. | |
1466 | ||
1467 | If the built in commands don't provide enough options, you will need | |
1468 | to write your own function in order to provide your dictionaries with | |
1469 | the values needed for custom templates. | |
1470 | ||
1471 | In this way, you can build your own code generator for any language | |
1472 | based on a set of predefined macros whos values you need to derive | |
1473 | from Emacs Lisp code yourself. | |
1474 | ||
1475 | For example: | |
1476 | ||
1477 | @example | |
1478 | (defun my-srecode-insert (template-name) | |
1479 | "Insert the template TEMPLATE-NAME into the current buffer at point." | |
1480 | ||
1481 | ;; Read in a template name. | |
1482 | (interactive (list (srecode-read-template-name "Template Name: "))) | |
1483 | (if (not (srecode-table)) | |
1484 | (error "No template table found for mode %s" major-mode)) | |
1485 | (let ((temp (srecode-template-get-table (srecode-table) template-name)) | |
1486 | ||
1487 | ;; Create a new dictionary | |
1488 | (newdict (srecode-create-dictionary))) | |
1489 | ||
1490 | (if (not temp) | |
1491 | (error "No Template named %s" template-name)) | |
1492 | ||
1493 | ;; Add some values into the dictionary! | |
1494 | (srecode-dictionary-set-value newdict "FOO" (my-get-value-of-foo)) | |
1495 | ;; Optionally show a section | |
1496 | (srecode-dictionary-show-section newdict "BLARG") | |
1497 | ||
1498 | ;; Add in several items over a loop | |
1499 | (let ((my-stuff (get-my-stuff-list))) | |
1500 | (while my-stuff | |
1501 | (let ((subdict (srecode-dictionary-add-section-dictionary | |
1502 | newdict "LOOP"))) | |
1503 | (srecode-dictionary-set-value subdict "NAME" (nth 0 my-stuff)) | |
1504 | (srecode-dictionary-set-value subdict "ARG" (nth 1 my-stuff)) | |
1505 | (srecode-dictionary-set-value subdict "MOOSE" (nth 2 my-stuff)) | |
1506 | ) | |
1507 | (setq my-stuff (cdr my-stuff))) | |
1508 | ||
1509 | ;; Some templates have arguments that need to be resolved. | |
1510 | (srecode-resolve-arguments temp newdict) | |
1511 | ||
1512 | ;; Do the expansion | |
1513 | (srecode-insert-fcn temp newdict) | |
1514 | )) | |
1515 | @end example | |
1516 | ||
1517 | Lets look at the key functions involved above: | |
1518 | ||
1519 | @section Interactive Completion: | |
1520 | ||
1521 | @defun srecode-read-template-name prompt | |
1522 | @anchor{srecode-read-template-name} | |
1523 | Completing read for Semantic Recoder template names. | |
1524 | @var{prompt} is used to query for the name of the template desired. | |
1525 | @end defun | |
1526 | ||
1527 | @section Template Lookup | |
1528 | ||
1529 | Even if your program does not query the user for a template name, you | |
1530 | will need to locate a template. First, you need to locate the table | |
1531 | to look the template up in. | |
1532 | ||
1533 | @defun srecode-table &optional mode | |
1534 | @anchor{srecode-table} | |
1535 | Return the currently active Semantic Recoder table for this buffer. | |
1536 | Optional argument @var{MODE} specifies the mode table to use. | |
1537 | @end defun | |
1538 | ||
1539 | ||
1540 | @defun srecode-template-get-table tab template-name &optional context application | |
1541 | @anchor{srecode-template-get-table} | |
1542 | Find in the template in mode table @var{TAB}, the template with @var{TEMPLATE-NAME}. | |
1543 | Optional argument @var{CONTEXT} specifies a context a particular template | |
1544 | would belong to. | |
1545 | Optional argument @var{APPLICATION} restricts searches to only template tables | |
1546 | belonging to a specific application. If @var{APPLICATION} is @code{nil}, then only | |
1547 | tables that do not belong to an application will be searched. | |
1548 | @end defun | |
1549 | ||
1550 | For purposes of an @srecode{} application, it is important to decide | |
cccaebd2 | 1551 | what to call your application, and use that with this method call. |
ac1d9dde EL |
1552 | |
1553 | @section Creating dictionaries | |
1554 | ||
1555 | Several dictionary calls are made in this example, including: | |
1556 | @table @code | |
1557 | @item srecode-create-dictionary | |
1558 | @item srecode-dictionary-set-value | |
1559 | @item srecode-dictionary-show-section | |
1560 | @item srecode-dictionary-add-section-dictionary | |
1561 | @end table | |
1562 | ||
1563 | These are documented more fully @ref{Dictionaries}. | |
1564 | ||
1565 | Also used is @code{srecode-resolve-arguments}. To learn more about | |
1566 | that, see @ref{Argument Resolution}. | |
1567 | ||
1568 | @section Template Insertion Commands | |
1569 | ||
1570 | There are several ways to insert a template. It is easiest to just | |
1571 | start with the main entry point. | |
1572 | ||
1573 | @defun srecode-insert-fcn template dictionary &optional stream | |
1574 | @anchor{srecode-insert-fcn} | |
1575 | Insert @var{template} using @var{dictionary} into @var{stream}. | |
1576 | If @var{stream} is nil, then use the current buffer. | |
1577 | @end defun | |
1578 | ||
1579 | @node Template Naming Conventions | |
1580 | @chapter Template Naming Conventions | |
1581 | ||
cccaebd2 | 1582 | For @srecode{} to work across languages reliably, templates need to |
ac1d9dde EL |
1583 | follow a predictable pattern. For every language of similar nature |
1584 | (OO, functional, doc based) if they all provide the same base | |
1585 | templates, then an application can be written against the base | |
1586 | templates, and it will work in each of the supported language. | |
1587 | ||
1588 | Having consistent templates also makes it easy to use those templates | |
1589 | from a user perspective during basic interactive insertion via | |
1590 | @code{srecode-minor-mode}. | |
1591 | ||
1592 | ||
1593 | NOTES ON THIS CHAPTER: | |
1594 | ||
1595 | These conventions are being worked on. Check w/ CEDET-DEVEL mailing | |
1596 | list if you want to support a language, or write an application and | |
1597 | provide your opinions on this topic. Any help is appreciated. | |
1598 | ||
1599 | ||
1600 | @section Context: File | |
1601 | ||
1602 | Each language should support the @code{file:empty} template. This | |
1603 | will generally use the default copyright insertion mechanism. | |
1604 | ||
1605 | @section Context: Declaration | |
1606 | ||
1607 | Functional languages should attempt to support the following: | |
1608 | ||
1609 | @table @code | |
1610 | @item function | |
1611 | A standalone function. Not a method, external method, or other. | |
1612 | @item method | |
cccaebd2 | 1613 | A method belonging to some class declared outside the textual bounds |
ac1d9dde EL |
1614 | of that class' declaration. |
1615 | @item variable | |
1616 | A global variable. | |
1617 | @item type | |
1618 | A data type. If the language supports several types of datatypes | |
1619 | then do not use this, use more specific ones instead. | |
1620 | @item class | |
1621 | For OO languages, use this instead of @code{type}. | |
1622 | @item include | |
1623 | Include files. | |
1624 | @end table | |
1625 | ||
1626 | For any @semantic{} tag class in your language, you will likely want | |
1627 | to have a corresponding template. | |
1628 | ||
1629 | In order for the @srecode{} function | |
1630 | @code{srecode-semantic-insert-tag} to work, you can create templates | |
1631 | similar to those mentioned above, except with @code{-tag} appended to | |
1632 | the end. This lets a template like @code{function} have user | |
1633 | conveniences when referencing @code{function-tag}, while also | |
1634 | allowing the tag inserter to do its job with a simpler template. | |
1635 | ||
1636 | @section Context: Classdef | |
1637 | ||
1638 | Inside a class definition. These are to be inserted inside the | |
1639 | textual bounds of a class declaration. | |
1640 | ||
1641 | @table @code | |
1642 | @item function | |
1643 | This would be a method of the class being inserted into. | |
1644 | @item constructor | |
1645 | @itemx destructor | |
1646 | Like @code{function} but specific to alloc/delete of an object. | |
1647 | @item variable | |
1648 | This would be a field of the class being inserted into. | |
1649 | @end table | |
1650 | ||
1651 | @section Context: Code | |
1652 | ||
1653 | Inside a body of code, such as a function or method body. | |
1654 | ||
f99f1641 | 1655 | ---no conventions yet. |
ac1d9dde EL |
1656 | |
1657 | @section Standard Dictionary Values | |
1658 | ||
1659 | For these variables to be useful, standard names should be used. | |
1660 | These values could be provided directly from a Semantic tag, or by an | |
1661 | application. | |
1662 | ||
1663 | @table @var | |
1664 | @item NAME | |
1665 | The name of the declaration being created. | |
1666 | @item PARENT | |
1667 | If the item belongs to some parent type, it would be the full name of | |
1668 | that type, including namespaces. | |
1669 | @item TYPE | |
1670 | A datatype name for a variable, or the return value of a function. | |
1671 | @item DOC | |
1672 | If there is some documentation associated with the item, then DOC | |
1673 | should contain the value. (Optional) | |
1674 | @item ARGS | |
1675 | The ARGS variable defines a section for 0 or more arguments to a function | |
1676 | or method. Each entry in ARGS will follow the rest of these naming | |
1677 | conventions, such as for NAME and TYPE. | |
1678 | @end table | |
1679 | ||
1680 | For templates used by @code{srecode-semantic-insert-tag}, there is | |
1681 | also the following useful dictionary values. | |
1682 | ||
1683 | @table @var | |
1684 | @item TAG | |
cccaebd2 | 1685 | A special insertion value TAG@. You can use semantic functions to turn |
ac1d9dde EL |
1686 | the tag into a string. |
1687 | @item HAVEDEFAULT | |
1688 | @itemx DEFAULT | |
1689 | Default value for a variable. | |
1690 | @end table | |
1691 | ||
1692 | @node Inserting Tag Lists | |
1693 | @chapter Inserting Tag Lists | |
1694 | ||
1695 | Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for | |
1696 | @srecode{} is to convert lists of tags, as produced by @semantic{} | |
1697 | back into code. | |
1698 | ||
1699 | A single function provides the interface for programs to do this, but | |
1700 | it requires any particular language to have provided the correct | |
1701 | templates to make it work. | |
1702 | ||
1703 | @defun srecode-semantic-insert-tag tag &optional style-option point-insert-fcn &rest dict-entries | |
1704 | @anchor{srecode-semantic-insert-tag} | |
1705 | Insert @var{tag} into a buffer using srecode templates at point. | |
1706 | ||
1707 | Optional @var{style-option} is a list of minor configuration of styles, | |
1708 | such as the symbol @code{'prototype} for prototype functions, or | |
1709 | @code{'system} for system includes, and @code{'doxygen}, for a doxygen style | |
1710 | comment. | |
1711 | ||
1712 | Optional third argument @var{point-insert-fcn} is a hook that is run after | |
1713 | @var{tag} is inserted that allows an opportunity to fill in the body of | |
1714 | some thing. This hook function is called with one argument, the @var{tag} | |
1715 | being inserted. | |
1716 | ||
1717 | The rest of the arguments are @var{dict-entries}. @var{dict-entries} | |
1718 | is of the form ( @var{name1} @var{value1} @var{name2} @var{value2} @dots{} NAMEn VALUEn). | |
1719 | ||
1720 | The exact template used is based on the current context. | |
1721 | The template used is found within the toplevel context as calculated | |
1722 | by @dfn{srecode-calculate-context}, such as @code{declaration}, @code{classdecl}, | |
1723 | or @code{code}. | |
1724 | ||
1725 | For various conditions, this function looks for a template with | |
1726 | the name @var{class}-tag, where @var{class} is the tag class. If it cannot | |
1727 | find that, it will look for that template in the | |
1728 | @code{declaration}context (if the current context was not @code{declaration}). | |
1729 | ||
1730 | If @var{prototype} is specified, it will first look for templates with | |
1731 | the name @var{class}-tag-prototype, or @var{class}-prototype as above. | |
1732 | ||
1733 | See @dfn{srecode-semantic-apply-tag-to-dict} for details on what is in | |
1734 | the dictionary when the templates are called. | |
1735 | ||
1736 | This function returns to location in the buffer where the | |
1737 | inserted tag @var{ends}, and will leave point inside the inserted | |
1738 | text based on any occurrence of a point-inserter. Templates such | |
1739 | as @dfn{function} will leave point where code might be inserted. | |
1740 | @end defun | |
1741 | ||
1742 | ||
1743 | @node Application Writing | |
1744 | @chapter Application Writing | |
1745 | ||
1746 | The main goal of @srecode{} is to provide a strong platform for | |
1747 | writing code generating applications. | |
1748 | ||
1749 | Any templates that are application specific should make an application | |
1750 | declaration for each template file they use. This prevents those | |
1751 | templates from being used outside of that application. | |
1752 | ||
1753 | For example, add this to a file: | |
1754 | @example | |
1755 | set application "getset" | |
1756 | @end example | |
1757 | ||
1758 | In your application Emacs Lisp code, you would then load those | |
1759 | templates. A typical initialization would look like this: | |
1760 | ||
1761 | @example | |
1762 | (srecode-load-tables-for-mode major-mode) | |
1763 | (srecode-load-tables-for-mode major-mode 'getset) | |
1764 | @end example | |
1765 | ||
1766 | These two lines will load in the base templates for the major mode, | |
1767 | and then the application specific templates. | |
1768 | ||
1769 | @defun srecode-load-tables-for-mode mmode &optional appname | |
1770 | @anchor{srecode-load-tables-for-mode} | |
1771 | Load all the template files for @var{mmode}. | |
1772 | Templates are found in the SRecode Template Map. | |
1773 | See @dfn{srecode-get-maps} for more. | |
1774 | @var{appname} is the name of an application. In this case, | |
1775 | all template files for that application will be loaded. | |
1776 | @end defun | |
1777 | ||
1778 | ||
f99f1641 | 1779 | todo: Add examples. Most core stuff is already described above. |
ac1d9dde EL |
1780 | |
1781 | ||
4c2dd4ee GM |
1782 | @node GNU Free Documentation License |
1783 | @appendix GNU Free Documentation License | |
1784 | @include doclicense.texi | |
1785 | ||
ac1d9dde EL |
1786 | |
1787 | @node Index | |
4c2dd4ee GM |
1788 | @unnumbered Index |
1789 | @printindex cp | |
ac1d9dde | 1790 | |
4c2dd4ee | 1791 | @iftex |
ac1d9dde | 1792 | @contents |
4c2dd4ee GM |
1793 | @summarycontents |
1794 | @end iftex | |
ac1d9dde EL |
1795 | |
1796 | @bye |