Requirements Specifications

Template Mode

Mark Ardis



Table of Contents

 

Introduction

Template-mode is a Gnu Emacs package that provides commands for inserting and manipulating text structures.  It is particularly useful for inserting standard fragments, such as boilerplate for documents or function headers for programs.  There are templates for major program fragments of C and Emacs-Lisp, as well as standard boilerplate for TeX documents.  Template-mode is designed to reduce the effort required to create major mode packages in Gnu Emacs, and to help make those packages consistent across document types.

 

Authors of major modes in Gnu Emacs often want to support standard operations.  Template-mode provides most of those standard features in a language-independent way. For example, most programming languages have standard loop constructs, though they differ in syntax from language to language. Users want to create those loop structures with a minimum of keystrokes, and with appropriate indentation provided automatically. Template-mode provides a mechanism so that the author of a major mode can describe the syntax of each loop construct, complete with indentation, in a template file. Users of the major mode can insert, delete, and traverse over any template with just a few keystrokes.

 

Special Terms/Abbreviations

  • template - a block of text that may contain placeholders for other templates.  There are 6 forms of templates:
    • Function - replaced by calling an Emacs Lisp function
    • Lexical - replaced by text that must match a regular expression
    • Repetition - replaced by a sequence of some other template
    • Selection - replaced by a choice from a list
    • Sequence - replaced by a block of text that may contain other placeholders
    • String - replaced by a block of text that may not contain other placeholders
  • placeholder - a special sequence of characters that may be replaced by a template or a text string.  There are 4 special forms of placeholders:
    • Destination - represents the intended final destination of point, always removed from the buffer after expanding
    • Text - replaced by any block of text not containing a newline
    • Textenter - similar to "Text" but saves the result for later use
    • Textlong - similar to "Text" but may contain newlines

Current Client System Diagram

[Needs to be added.]

User Characteristics

Users

There are two types of users of template-mode:

  • authors of major modes
  • users of those major modes

Authors of major modes are expected to be familiar with loading and calling other Gnu Emacs functions. In order to make effective use of template-mode they will need to understand how template-mode loads its template files.  Other users only need to know how to invoke the standard operations of template-mode, such as expanding a template.

User's Environment

It is expected that users of template-mode will load it from a standard library. Option variables are provided to define that location. Many other option variables are provided to define the syntax of templates and the behavior of template-mode functions.

Requirements

1. External Interfaces

Unspecified at this time.

2. Functional Requirements

2.1 There should be a mechanism for defining and storing templates.

2.2 There should be a mechanism for loading templates from a library or a specific file.

2.3 There should be a mechanism for expanding placeholders by their associated templates.

2.4 There should be a mechanism for deleting a placeholder.

2.5 There should be a mechanism for traversing forward or backward to the next placeholder.

2.6 There should be mechanisms for turning template-mode off and on.

3. Performance Requirements

There are no specific performance requirements, other than reasonable response time for the function invoked.  That is, the user should not be surprised by long execution times for simple operations.

4. Logical Database Requirements

NA - there is no database.

5. Design Constraints

All code should be written in a style that is consistent with stadard practice of Gnu Emacs Lisp.

6. Software System Attributes

6.1 Reliability

The software should include a simple example to use in testing its installation.


6.2 Availability

NA


6.3 Security

NA


6.4 Maintainability

The software should be well-documented, and written in a modular fashion. All global variables should be described.


6.5 Portability

The software should work correctly on any system that runs Gnu Emacs Lisp.  That is, it should make no new requirements on the underlying system.

7. Other Requirements

There are no other requirements.

Use Case Model

[Needs to be added.]

Problem Domain Model

[Needs to be added.]

Scope of the Project

[Needs to be added.]

Client Materials

No additional materials are needed.

Reference Materials

  • Gnu Emacs Lisp Manual, Richard Stallman, blah blah blah.

To Do List

<List of items to be completed in THIS artifact.>
 

Items

Complete remaining sections

Revision History

Date

Name

Revision

 01/26/2003 

Mark Ardis

Initial version