Wisi Version 4.3
Next: Grammar Actions, Previous: Top, Up: Top [Contents][Index]
“wisi” used to be an acronym, but now it’s just a name.
The wisi package provides an elisp interface to an external parser. It assumes the parser generator package WisiToken (https://stephe-leake.org/ada/wisitoken.html, implemented in Ada), but can use any parser that meets the same API. wisi provides several grammar actions, to implement indentation, navigating, and syntax highlighting (fontification).
wisi also provides an extension to Emacs project.el, providing operations useful for compilation and cross-reference.
Next: Project extension, Previous: Overview, Up: Top [Contents][Index]
Grammar actions are specified in the grammar file, in a nonterminal declaration. We assume the user is familiar with parser grammars and grammar actions. For example, an “if” statement can be declared as:
if_statement
: 'if' expression 'then' statements elsif_list 'else' statements 'end' 'if' ';'
%((wisi-statement-action [1 statement-start 3 motion 6 motion 10 statement-end])
(wisi-motion-action [1 3 5 6 10])
(wisi-indent-action [nil
ada-indent-broken
nil
[(wisi-block ada-indent) ada-indent] nil nil
[(wisi-block ada-indent) ada-indent] nil nil nil]))%
The item before : is the “left hand side”, or
“nonterminal”. The list of tokens after : is the “right hand
side”; in general there can be more than one right hand side for each
nonterminal (separated by |).
The items enclosed in “%()%” are the grammar actions. They are
specified as list of elisp forms; an earlier version of the wisi
package generated a parser in elisp, now it only generates Ada. We
keep the elisp form for grammar actions because it is compact, and
easier to read and write than the equivalent Ada code. The WisiToken
tool wisi-bnf-generate converts the elisp into the required Ada
statements.
There are two classes of actions; in-parse and post-parse. WisiToken
calls these “semantic checks” and “semantic actions”. The in-parse
actions are done as parsing procedes; they provide extra checks that
can cause the parse to fail. Currently the only one provided is
match-names; it is used to check that the declaration and end
names in named Ada blocks are the same (which can aid significantly in
error correction). In the grammar file, in-parse actions are specified
in a second %()% block, which can be omitted if empty. In this
document, the term “action” generally means “post-parse action”,
we use “in-parse action” unless the meaning is clear from context.
Executing the wisi grammar actions creates text properties in the source file; those text properties are then used by elisp code for various purposes. The text properties created are:
wisi-cacheThis should be named wisi-navigate, but isn’t for historical
reasons (there used to be only one kind of text property).
The property contains a wisi-cache object, containing:
nontermThe nonterminal in the grammar production that specified the action that produced this text property.
tokenA token identifier naming a token in the production right hand side containing the text this text property is applied to.
lastThe position of the last character in the token, relative to the first character (0 indexed). The text property is only applied to the first character in the token (mostly for historical reasons).
classA token class; see the list of possible values in
wisi-statement-action below.
containingA marker pointing to the start of the containing token for this token;
only nil for the outermost containing token in a file.
prevA marker pointing to the previous “motion token” in the statement or declaration. These are normally language keywords, but can be other things.
nextA marker pointing to the next “motion token” in the statement or declaration.
endA marker pointing to the end of the statement or declaration.
wisi provides motion commands for going to the various markers.
wisi-nameContains no data, applied to a “name” of some sort. wisi provides
commands for finding the next/previous name, and returning the
text. Useful for the names of subprograms, which can then be used to
build a completion table; see wisi-xref-identifier-completion-table.
font-lock-faceThe standard font-lock property, specifying the face for the text.
Some major modes do not use this for simple keywords; they use font-lock regular expressions instead. One reason for this is so keywords are still highlighted when the parser fails, which can happen if there are severe syntax errors.
Other items, like function, package, and type names, are typically
marked with font-lock-face by the parser.
fontifiedAnother standard font-lock text property; applied whenever
font-lock-face is.
wisi-indentContains the indent (in characters) for the next line; applied to the newline character at the end of the preceding line. The first line in a buffer is assumed to have indent 0.
Each action is classified as one of navigate, face, indent,
in-parse; when actions are executed, only one of the first three classes
is executed (in-parse is always executed). This reflects the reasons
the parser is run; to figure out how to go somehere (end of current
statement, start of current procedure, etc), to apply faces for syntax
highlighting, or to indent the code.
Next: Indent actions, Previous: Navigate actions, Up: Grammar Actions [Contents][Index]
wisi-face-mark-action [INDEX CLASS ...]The argument is a vector; alternating elements form pairs of INDEX
CLASS, where class is one of prefix, suffix.
Mark the tokens as part of a compound name, for use by later face actions.
wisi-face-apply-action [TOKEN PREFIX-FACE SUFFIX-FACE ...]The argument is a vector; triples of items specify TOKEN,
PREFIX-FACE, SUFFIX-FACE. The faces are the elisp names of face
objects (which must declared by an %elisp_face declaration).
If the token is a nonterminal, and it has been marked by a previous
wisi-face-mark-action, the specified faces are applied to the
prefix and suffix in the token as font-lock-face text
properties.
If the token is a terminal, or a non-terminal with no face mark, the suffix face is applied to the entire text contained by the token.
wisi-face-apply-list-action [TOKEN PREFIX-FACE SUFFIX-FACE ...]Similar to ’wisi-face-apply-action’, but applies faces to all tokens
marked by wisi-face-mark-action in each indicated production
token, and does not apply a face if there are no such marks.
Next: In-parse actions, Previous: Face actions, Up: Grammar Actions [Contents][Index]
Indents are computed for each line in a cumulative way as the grammar
actions are executed. Initially, the indent for all lines are set to
nil, which means “not computed”; this is not the same as the
value 0. The grammar actions are executed in a bottom-up
fashion; low level productions are executed before higher level
ones. In general, the indent action for a production specifies a
“delta indent”; the indent for a line is incremented by that
amount. When all productions in a parse tree have been processed, the
indent has been computed for all lines.
Indent actions specify a delta indent for each token in a production. If the token is a nonterminal that contains multiple lines of text, the delta indent applies to the lines where the first token on the line is contained by the nonterminal.
When a delta indent is applied to the indent for a line, it is either
added or ignored. We call the token whose delta indent is being
applied the “controlling” token. The indent for each line has a
field storing the line number of the last controlling token that added
to the indent. If the line number of the controlling token for the
delta indent begin applied is the same as the stored controlling token
line number, the indent is ignored. Indent example for
explanations of why this rule is needed. On the other hand, it may be
necessary to use wisi-block or wisi-anchored to override
this rule.
Indents are often given as a function call; the arguments to the
function can be other function calls, or integer
expressions. wisitoken-bnf-generate supports only simple
integer expressions; those using integers, integer-valued variables, +
(plus), - (minus), and * (multiply). All expressions are lisp forms;
“ada-indent plus 1” is written as (+ ada-indent 1).
Indent for comments are computed in the same way, except that the
delta that applies to a comment that follows a token is given by the
indent action entry for the next token. If a token is the last in a
production, the comment indent is nil. These rules often give
the wrong indent for a comment, so they can be overridden by specifing
a comment indent for a token using [CODE-INDENT
COMMENT-INDENT]; see below. Indent functions can also modify how
comments are indented.
wisi-indent-action [DELTA ...]The argument is a vector, giving a delta indent for each token in the production right-hand side.
For terminals, the indents only have meaning, and are only computed, if the token is the first on a line. For nonterminals, the indent is applied to all lines where the first token on the line is contained in the nonterminal.
An indent can have several forms. In the descriptions below, the
“current token” is the token in the production right hand side at
the same position as the indent expression in the
wisi-indent-action argument list.
The simplest delta indent.
An integer delta indent; the value can be changed at runtime.
The variable is an elisp variable; the name is translated to an Ada
identifier by replacing “-” with “_”, and applying
Camel_Case. The translated name must identify a directly
visible run-time Ada integer variable; this is checked at Ada compile
time (variables declared in a separate package can be made visible by
placing a with clause in a %code declaration in the grammar
file). The elisp variable value is copied to the Ada variable value at
the start of each indent compute session.
For example, in ada-mode two indent variable names are ada-indent
and ada-indent-broken, giving the basic ident, and the
continuation line indent. They are runtime variables so different
projects can specify them as part of a coding standard.
A function that computes a delta indent. See Indent functions.
A vector giving separate indents for code and comments.
Normally, the indent for trailing comments (on lines with no code, after all code in the token) is given by the indent of the first line of code in the following token in the production; this overrides that and the comment indent is given by COMMENT-INDENT applied to the current token.
When the current token is the last, and a separate comment indent is not specified, the comment indent is nil.
Comment lines that are not trailing (that is, they are between tokens in the nonterminal being indented) are indented by CODE-INDENT.
Specifies that the indent applies to the token with the same label. If any argument in an indent action is labeled, all must be labeled, and thus all tokens in the production must be labeled. This can improve readability in a long production.
When the grammar file uses EBNF meta-syntax, implicit labels are automatically generated for all tokens that are not explicitly labeled; this allows keeping track of which optional tokens are left out when the production is converted to BNF internally.
Next: Indent example, Up: Indent actions [Contents][Index]
wisi-block DELTASets the delta indent for the current token to be DELTA, and ignores
the controlling token line when adding delta indents. This is usually
needed in block statements; Indent example if_statement.
DELTA can be any indent expression, except a variant of
wisi-hanging.
wisi-anchored ANCHOR OFFSETSets the delta indent for the current token to be OFFSET (an integer expression) from the start of ANCHOR (a token index). Subsequent higher level delta indents are ignored; the current token is “anchored to” ANCHOR.
A trailing comment following the current token is indented the same as the code in the token.
wisi-anchored% ANCHOR OFFSETSets the delta indent for the current token to be OFFSET (an integer expression) from a containing left parenthesis in the line containing ANCHOR (a token index), or the start of the line containing ANCHOR if there is no such paren; the current token is “anchored to” the paren or the start of the line. Subsequent higher level delta indents are ignored.
wisi-hanging DELTA-1 DELTA-2Use DELTA-1 for the first line in the current token, DELTA-2 for the rest. Trailing comments use DELTA-1 if there is only one code line, DELTA-2 if there is more than one.
DELTA-1 and DELTA-2 can be any ident expression, except a variant of
wisi-hanging.
wisi-hanging is useful when the lower level productions for the
current token do not have indent actions.
wisi-hanging% DELTA-1 DELTA-2If the first token in the nonterminal is first on its line, use DELTA-1 for the first line, DELTA-2 for the rest. Otherwise, use DELTA-1 for all lines.
wisi-hanging* DELTA-1 DELTA-2If the first token in the nonterminal is first on its line, use DELTA-1 for the first line, DELTA-1 + DELTA-2 for the rest. Otherwise, use DELTA-2 for all lines.
Language-specific functionLanguage-specific indent functions are specified by an
%elisp_indent declaration in the grammar file. Each function
declaration specifies how many arguments it accepts; this is checked
at grammar generation time. Each argument is a delta indent expression
as described above, a token index, or a token ID prefixed by '
(to allow distinguishing token IDs from variable names).
Previous: Indent functions, Up: Indent actions [Contents][Index]
To illustrate how indents are computed, we walk thru the computation for some example code.
The simple grammar used for this example is:
if_statement
: 'if' expression 'then' statements 'end' 'if' ';'
%((wisi-indent-action [nil
ada-indent-broken
nil
[(wisi-block ada-indent) ada-indent]
nil nil nil]))%
expression
: term
%((wisi-indent-action [(wisi-hanging nil ada-indent-broken)]))%
term
: primary
| primary '+' primary
| primary '<' primary
| term 'and' term
primary : integer | identifier | function_call
function_call
: identifier formal_part
%((wisi-indent-action [nil ada-indent-broken]))%
formal_part
: '(' expression_list ')'
%((wisi-indent-action [nil
(wisi-anchored 1 1)
(wisi-anchored 1 0)]))%
expression_list : expression | expression_list ',' expression
statements : statement | statements statement
statement : function_call ';' | assigment | if_statment
assign_value : ':=' expression
assignment
: identifier assign_value ';'
%((wisi-indent-action [nil (wisi-hanging ada-indent-broken (* 2 ada-indent-broken)) nil]))%
Note that we have split out assign_value from
assignment, so we can apply the wisi-hanging indent
function to it; see the first example below for an explanation of why
this is needed.
The indent variables have the values:
ada-indent 3 ada-indent-broken 2
First we consider a simple example (the line numbers and indents are on the left):
1: nil : G 2: nil : := 3: nil : F + 4: nil : Compute_Something 5: nil : (Arg_1, 6: nil : H + 7: nil : I);
The assignment statement is fully spread out on different lines, as might be required if the names or subexpressions are long. In this case, none of the delta indents are ignored when applied to a line (except anchored lines), which is why they all need to be present in the indent actions. Thus we can leave out the stored controlling token in the line indents for this example.
Indents are computed in bottom up order; the first indent action
computed in this code is for expression H + I lines 6
and 7; the delta indent expression is:
[(wisi-hanging nil ada-indent-broken) ada-indent-broken]
This gives separate indents for the code and a trailing comment; there is no trailing comment in this example (there is one in the next example). This gives a delta indent of nil for line 6, and 2 for line 7.
The next indent action is for formal_part (Arg_1, H + I)
lines 5, 6. The indent action is:
%((wisi-indent-action [nil (wisi-anchored 1 1) (wisi-anchored 1 0)]))%
For each token, the delta indent computed by this is:
( : nilLeaves line 5 at nil.
expression_list : (wisi-anchored 1 1)The first 1 is token indenx of the anchor token; the left
parenthesis on line 5. The second 1 is the offset from the
anchor; thus the delta indent is Anchored, 5, 1; anchored to
line 5 with an offset of 1. This delta indent is applied to the lines
whose first tokens are contained by the expression_list; that
is lines 6 and 7. Line 6 indent is currently nil, so the indent is set
to Anchored, 5, 1. Line 7 indent is currently 2, so that is
added to 1, setting the indent to Anchored, 5, 3.
) : (wisi-anchored 1 1)’)’ is not first on a line, so this leaves line 6 indent unchanged.
Next indent action is function_call Compute_Something
(Arg_1, H + I) on lines 4 .. 7. The indent action is
%((wisi-indent-action [nil ada-indent-broken]))%; this applies
a delta indent of 2 to the formal_part on lines 5 .. 7,
leaving line 5 at 4, and 6 and 7 unchanged.
Next is expression F + Compute_Something (Arg_1, H + I)
on lines 3 .. 7. This computes a delta indent of nil for line 3, and
2 for lines 4 .. 7, leaving 3 at nil, 4 at 2, 5 at 6, and 6 and 7
unchanged.
Last indent action is node 16 assignment on lines 1 .. 6; the
indent is (wisi-hanging ada-indent-broken (* 2
ada-indent-broken)), applied to all the lines contained by
assign_value, which is lines 2 thru 7. This gives a delta
indent of 2 for line 2, and 4 for lines 3 .. 7. This gives the
indents:
: 12345678901 1: nil : G 2: 2 : := 3: 4 : F + 4: 6 : Compute_Something 5: 8 : (Arg_1, 6: Anchored, 5, 1 : H + 7: Anchored, 5, 3 : I);
The final step is compute all the anchored lines; for line 6, we add 1 to the indent for line 5, leaving 9; for line 7, add 3, leaving 11.
Now consider a more extensive example:
1: if A < B and 2: C < D 3: -- comment on expression 4: then 5: G := F + Compute_Something 6: (Arg_1, 7: Arg_2); 8: -- comment on statement 9: 10: Do_E; 11: 12: -- comment before 'end if' 13: end if;
Here the assignment is on fewer lines, illustrating why we need the
rule about ignoring some delta indents, and wisi-block to
override that rule.
To understand the order in which indents are computed, we need the syntax tree produced by parsing this code; that is shown here, with node numbers on the left for reference. Note that comments are stored in the node containing the terminal token node preceding the comment. Node 20 ’formal_part’ is empty; “Do_E” has no arguments.
1 if_statement
2 'if'
3 expression
4 term
5 primary
6 identifier "A"
7 '<'
8 primary
9 identifier "B"
10 'and'
11 term
12 primary
13 identifier "C"
14 '<'
15 primary
16 identifier "D", "-- comment on expression"
17 'then'
18 statements
19 statements
20 statement
21 assignment
22 identifier "G"
23 assign_value
24 ':='
25 expression
26 term
27 primary
28 identifier "F"
29 '+'
30 primary
31 function_call
32 identifier "Compute_Something"
33 formal_part
34 '('
35 expression_list
36 expression_list
37 expression
38 term
39 primary
40 identifier "Arg_1"
41 ','
42 expression
43 term
44 primary
45 identifier "Arg_2"
46 ')'
47 ';' "-- comment on statement", blank line
48 statement
49 function_call
50 identifier "Do_E"
51 formal_part
52 ';', blank line, "-- comment before 'end if'"
53 'end'
54 'if'
55 ';'
Actions are computed by traversing the tree depth first. Thus the
first node considered is node 6; it is an identifier, which is
a terminal token and has no indent action. The next nodes considered
are 5, 7, 9, 8, 4, 10, 13, 12, 14, 16, 15; all have no action. Next is
node 3 expression on lines 1 and 2, which has the indent
action:
[(wisi-hanging nil ada-indent-broken) ada-indent-broken]
This gives separate indents for the code and the trailing comment.
The code is A < B and C < D on lines 1 and 2, with
a trailing comment of -- comment on expression on line 3. Since the
first token in the expression follows if on line 1, it is not first on
the line; thus wisi-hanging gives a delta indent of 2 for line
2, leaving line 1 at nil.
The comment on line 3 is given an indent of 2. Note that if the comment indent had not been given separately in this indent action, it would have been given the indent of the next token, which is nil.
The stored controlling token line for lines 2 and 3 is 1.
Next is node 37 expression Arg_1 line 9; it is all on one line
and not the first token, so the indent is left at nil. Similarly for
node 45 expression Arg_2 line 10.
At this point, the indents for all the lines are (the stored controlling token line and indent is given after the line number):
1: nil nil : if A < B and 2: 1 2 : C < D 3: 1 2 : -- comment on expression 4: nil nil : then 5: nil nil : G := A + Compute_Something 6: nil nil : (Arg_1, 7: nil nil : Arg_2); 8: nil nil : -- comment on statement 9: nil nil : 10: nil nil : Do_E; 11: nil nil : 12: nil nil : -- comment before 'end if' 13: nil nil : end if;
Next indent action is node 33 formal_part (Arg_1, Arg_2)
lines 6 and 7. The indent action is
%((wisi-indent-action [nil
(wisi-anchored 1 1)
(wisi-anchored 1 0)]))%
This computes a delta indent for the expression_list of
Anchored, 5, 1); anchored to the left parenthesis on line 5
with an offset of 1. This delta indent is applied to the lines whose
first tokens are contained by the expression_list; that is just
line 7. Since the indent for line 7 is currently nil, it is set to
Anchored, 5, 1), controlling token line 5.
Next is node 31 function_call Compute_Something (Arg_1,
Arg_2) on lines 5 .. 7. The indent action is [nil
ada-indent-broken], which gives a delta indent of 2 for the
formal_part. This is applied to lines 6 and 7, leaving line 6
at 2, stored controlling token line 5; and 7 unchanged.
Next is node 25 expression F + Compute_Something (Arg_1,
Arg_2) on lines 5 .. 7; this computes a delta indent of 2 for lines
6 and 7. The controlling token line is 5, and the stored controlling
token for line 6 is also 5, so this delta indent is ignored for line
6. Line 7 is anchored, so the delta indent is also ignored. Thus the
indent for lines 6 and 7 are unchanged.
Next is node 16 assignment on lines 5 .. 7. The indent for
assign_value is (wisi-hanging ada-indent-broken (* 2
ada-indent-broken)); this computes a delta indent of 2 for lines 6
and 7; it is ignored as the delta indent from node 25 was.
The comment and blank line on lines 8 and 9 are stored in node 47, and there is no following token in the production, so the delta indent for line 8 is nil.
The next action computed is node 21 function_call Do_E;
on line 10. The indent action is %((wisi-indent-action [nil
ada-indent-broken]))%; since the code is all on one line this leaves
the indent for line 10 at nil. The indent for the trailing comment and
blank line on lines 11 and 12 are also left at nil.
At this point, the indents are:
1: nil nil : if A < B and 2: 1 2 : C < D 3: 1 2 : -- comment on expression 4: nil nil : then 5: nil nil : G := F + Compute_Something 6: 5 2 : (Arg_1, 7: 6 Anchored 5 1 : Arg_2); 8: nil nil : -- comment on statement 9: nil nil : 10: nil nil : Do_E; 11: nil nil : 12: nil nil : -- comment before 'end if' 13: nil nil : end if;
The final indent action is for node 1 if_statement on lines 1
thru 13. The indent for each token in the production is:
if: nilLeaves line 1 at nil.
expression: ada-indent-brokenThe expression is A < B and C < D on lines 1 and 2, with a
comment on line 3; the controlling token line is 1, the same as the
stored controlling token line for lines 2 and 3, so this is ignored.
then: nilApplies delta of nil to line 4.
Note that specifying the indent for the comment following an
expression in the expression indent action enforces a style of
indenting the comment with the last line of the expression.
statements: [(wisi-block ada-indent) ada-indent]Applies a delta indent of 3 to the code and comment on lines 5 thru
10, and 3 to the trailing comment on lines 11 and 12. The controlling
token line is 5, so this delta would be ignored for line 6; this is
why we need wisi-block, which sets controlling token line to
invalid. The delta is ignored for the Anchored line 7.
Note that the indent for comments after statements is given here, not at a lower level; it would be tedious to add it to each statement.
end if; : nilLeaves line 13 at nil.
The indents so far:
1: nil nil : if A < B and 2: 1 2 : C < D 3: 1 2 : -- comment on expression 4: nil nil : then 5: 5 3 : G := F + Compute_Something 6: 5 5 : (Arg_1, 7: 5 Anchored 5 1 : Arg_2); 8: 5 3 : -- comment on statement 9: 5 3 : 10: 5 3 : Do_E; 11: 5 3 : 12: 5 3 : -- comment before 'end if' 13: nil nil : end if;
The final step is compute the anchored lines; that sets the indent for line 7 to 6.
In a full grammar, the top production should specify an indent of 0, not nil, for tokens that are not indented; then every line will have a non-nil indent.
However, in normal operation a nil indent is treated as 0; the
wisi-indent text property is not set for lines that have nil
indent, and wisi-indent-region detects that and uses 0 for the
indent. You can set the variable wisi-debug to a value > 0 to
signal an error for nil indents; this is useful to catch indent errors
during grammar development.
Previous: Indent actions, Up: Grammar Actions [Contents][Index]
wisi-propagate-name TOKENThe argument is a token index. Set the name component of the
left-hand-side parse-time token object to the name component of
the identified token, if it is not empty. Otherwise use the
byte_region component.
wisi-merge-name FIRST-TOKEN, LAST-TOKENThe arguments are token indices, giving a range of tokens. LAST-TOKEN may be omitted if it is the same as FIRST-TOKEN.
Set the name component of the left-hand-side to the merger of
the name or byte_region components of the identified tokens.
wisi-match-name START-TOKEN END-TOKENThe arguments are token indices. Compare the text contained by the
name (or byte_region if name is empty) token
components for START-TOKEN and END-TOKEN; signal a parse error if they
are different.
The behavior when a name is missing is determined by the runtime
language variable given in the %end_names_optional_option
declaration; if True, a missing name that is supposed to match a
present name is an error. Both names missing is not an error (assuming
that is allowed by the grammar).
Next: GNU Free Documentation License, Previous: Grammar Actions, Up: Top [Contents][Index]
wisi defines the cl-defstuct wisi-prj, with operations
suitable for compilation and cross-reference.
In order to use wisi projects, the user must write project files and
customize project-find-functions and
xref-backend-functions.
Next: Selecting projects, Up: Project extension [Contents][Index]
Project file names must have an extension given by
wisi-prj-file-extensions (default .adp, .prj).
Project files have a simple syntax; they may be edited directly. Each line specifies a project variable name and its value, separated by “=”:
src_dir=/Projects/my_project/src_1 src_dir=/Projects/my_project/src_2
There must be no space between the variable name and “=”, and no trailing spaces after the value.
Any line that does not have an “=” is a comment.
Some variables (like src_dir) are lists; each line in the
project file specifies one element of the list. The value on the last
line is the last element in the list.
A variable name that starts with $ is set as a process
environment variable, for processes launched from Emacs for the
project.
In values, process environment variables can be referenced
using the normal $var syntax.
In values, relative file names are expanded relative to the directory containing the project file.
Here is the list of project variables defined by wisi; major modes may add more.
casing [slot: case-exception-files]List of files containing casing exceptions, either absolute, relative to the project file directory, or found on the project file path. See Casing exception files.
import_env_var [slot: file-env]Copies an environment variable from process-environment.
src_dir [slot: source-path]A list of directories to search for source files.
$<name> [slot: file-env]Set an environment variable name in the local file-env;
it may be referenced in subsequent project file statements, and in
processes spawned by the project.
Next: Casing exception files, Previous: Project files, Up: Project extension [Contents][Index]
The current project can either be indicated by a global variable (called a “selected project”), or depend on the current buffer.
In addition, the project file can be parsed each time it is needed, or the result cached to improve response time,
One reason to use a selected project is to handle a hierarchy of
projects; if projects B and C both depend on library project A, then
when in a file of project A, there is no way to determine which of the
three projects to return. So the user must indicate which is active,
by using one of wisi-prj-select-file or
wisi-prj-select-cache.
In addition, if changing from one project to another requires setting
global resources that must also be unset (such as a syntax propertize
hook or compilation filter hook), then the project should define
wisi-prj-deselect in addition to wisi-prj-select. Such
projects require having a selected current project, so it can be
deselected before a new one is selected. One example of such projects
is ada-mode.
One way to declare each project is to add a Local Variables section in the main Makefile for the project; when the Makefile is first visited, the project is declared. In the examples here, we assume that approach is used; each gives an :eval line.
Note that wisi-prj-current-parse and
wisi-prj-current-cached always succeed after some project is
selected; no functions after them on project-find-functions will
be called. That’s why the depth is 90 for those in the examples.
(add-hook 'project-find-functions #'wisi-prj-find-dominating-parse 0) :eval (wisi-prj-set-dominating "foo.prj" (foo-prj-default "prj-name"))
wisi-prj-set-dominating declares the name of a project file with a
default project object, and ensures that the current buffer file name
is in wisi-prj--dominating.
wisi-prj-find-dominating-parse looks for the filenames in
wisi-prj--dominiating in the parent directories of the current
buffer. When one is found, the associated project file is parsed,
using the default project object to dispatch to the appropriate
parsers. Then the final project object is returned.
(add-hook 'project-find-functions #'wisi-prj-find-dominating-cached 0) :eval (wisi-prj-cache-dominating "foo.prj" (foo-prj-default "prj-name"))
wisi-prj-cache-dominating declares the project file, parses it,
and saves the project object in a cache indexed by the absolute
project file name.
wisi-prj-find-dominating-cached finds the dominating
project file, and retrieves the object from the cache.
(add-hook 'project-find-functions #'wisi-prj-current-parse 90) :eval: (wisi-prj-select-file <prj-file> (foo-prj-default "prj-name"))
wisi-prj-select-file sets the project file as the current
project, and saves the default project object.
wisi-prj-current-parse parses the current project file, using
the saved default project object, and returns the project object.
(add-hook 'project-find-functions #'wisi-prj-current-cached 90) :eval: (wisi-prj-select-cache <prj-file> (foo-prj-default "prj-name"))
wisi-prj-select-cache parses the project file, caches the
project object.
wisi-prj-current-cached returns the cached current project
object.
In addition, the user should set xref-backend-functions. Currently,
there is only one choice for wisi projects:
(add-to-list 'xref-backend-functions #'wisi-prj-xref-backend 90)
wisi-prj-xref-backend returns the current wisi project object.
Next: Other project functions, Previous: Selecting projects, Up: Project extension [Contents][Index]
Each line in a case exception file specifies the casing of one word or word fragment. If an exception is defined in multiple files, the first occurrence is used.
If the word starts with an asterisk (*), it defines the casing
of a word fragment (or “substring”); part of a word between two
underscores or word boundary.
For example:
DOD *IO GNAT
The word fragment *IO applies to any word containing “_io”;
Text_IO, Hardware_IO, etc.
Previous: Casing exception files, Up: Project extension [Contents][Index]
wisi-refresh-prj-cache (not-full)Refreshes all cached data in the project, and re-selects the project. If NOT-FULL is non-nil, slow refresh operations are skipped.
This reparses the project file, and any cross reference information.
wisi-prj-select-dominating (dominating-file)Find a wisi-prj matching DOMINATING-FILE (defaults to the current buffer file). If the associated project is current, do nothing. If it is not current, select it.
This is useful before running ‘compilation-start’, to ensure the correct project is current.
Next: Index, Previous: Project extension, Up: Top [Contents][Index]
Copyright © 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc. https://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Previous: GNU Free Documentation License, Up: Top [Contents][Index]