doc_modes.pl -- Analyse PlDoc mode declarations

This module analyzes the formal part of the documentation of a predicate. The formal part is processed by read_term/3 using the operator declarations in this module.

author: - Jan Wielemaker
license: - GPL

process_modes(+Lines:lines, +Module, +FilePos, -Modes:list, -Args:list(atom), -RestLines:lines) is det

Process the formal header lines (upto the first blank line), returning the remaining lines and the names of the arguments used in the various header lines.

Arguments:

`FilePos`	- Term File:Line with the position of comment
`Modes`	- List if `mode(Head, Bindings)` terms
`Args`	- List of argument-names appearing in modes

mode_lines(+Lines, -ModeText:codes, ?ModeTail:codes, -Lines) is det[private]

Extract the formal header. For %%/%! comments these are all lines starting with %%/%!. For /** comments, first skip empty lines and then take all lines upto the first blank line. Skipping empty lines allows for comments using this style:

/**
 * predicate(+arg1:type1, ?arg2:type2) is det
 ...

modes(+Text:codes, +Module, +FilePos, -ModeDecls) is det[private]

Read mode declaration. This consists of a number of Prolog terms which may or may not be closed by a Prolog full-stop.

Arguments:

`Text`	- Input text as list of codes.
`Module`	- `Module` the comment comes from
`ModeDecls`	- List of `mode(Term, Bindings)`

mode_syntax_error(+ErrorTerm) is det[private]

Print syntax errors in mode declarations. Currently, this is suppressed unless the flag pldoc_errors is specified.

prepare_module_operators is det[private]

Import operators from current source module.

public_operators(+Module, -List:list(op(Pri,Assoc,Name))) is det[private]

List is the list of operators exported from Module through its module header.

extract_varnames(+Bindings, -VarNames, ?VarTail) is det[private]

Extract the variables names.

Arguments:

`Bindings`	- Nested list of Name=Var
`VarNames`	- List of variable names
`VarTail`	- Tail of `VarNames`

compile_mode(+Mode, -Compiled) is det

Compile a PlDoc mode declararion into a term

mode(Head,
Determinism)

Arguments:

Mode

- List if mode-terms. See process_modes/6.

mode(:Head, ?Det) is nondet

True if there is a mode-declaration for Head with Det.

Arguments:

`Head`	- Callable term. Arguments are a mode-indicator followed by a type.
`Det`	- One of `unknown`, `det`, `semidet`, or `nondet`.

is_mode(@Head) is semidet

True if Head is a valid mode-term.

mode_indicator(?Ind:atom) is nondet

Our defined argument-mode indicators

modes_to_predicate_indicators(+Modes:list, -PI:list) is det

Create a list of predicate indicators represented by Modes. Each predicate indicator is of the form atom/integer for normal predicates or atom//integer for DCG rules.

Arguments:

`Modes`	- Mode-list as produced by process_modes/5
`PI`	- List of Name/Arity or Name//Arity without duplicates

compile_clause(:Term, +FilePos) is det

Add a clause to the compiled program. Unlike assert/1, this associates the clause with the given source-location, makes it static code and removes the clause if the file is reloaded. Finally, as we create clauses one-by-one, we define our predicates as discontiguous.

Arguments:

`Term`	- Clause-term
`FilePos`	- `Term` of the form File:Line, where File is a canonical filename.