| | 1 | = Spec entity = |
| | 2 | |
| | 3 | Spec entities correspond to ''-spec'' attributes in erlang sources. The specification for a given function is commonly present in the module where the function is defined, but it can also be placed in header files or other modules. A function might have more than one specification even if it consists of only one clause. Please note that in our representation, there is no "1:1" correlation between function clauses and ''-spec'' attributes, so any given function clause has all specs of the entire function. |
| | 4 | |
| | 5 | == Initial selector == |
| | 6 | A ''-spec'' attribute can be indicated by a given position. In this case the {{{@spec}}} initial-selector returns the spec entity corresponding to the indicated attribute in the source. |
| | 7 | |
| | 8 | == Selectors == |
| | 9 | |
| | 10 | ''The type of the result elements are indicated in parenthesis.'' |
| | 11 | |
| | 12 | * {{{function}}} (''function''): The function that has this spec. |
| | 13 | * {{{file}}} (''file''): The file in which the spec was defined. |
| | 14 | * {{{refmod}}} (''file''): The file to which the spec pertains. (If a module identifier has been used in the spec, the result may differ from the defining file.) |
| | 15 | * {{{returntype}}} (''type''): Possible return types of the spec. |
| | 16 | * {{{guardtype}}} (''type''): Types of the spec-guards. |
| | 17 | * {{{arguments}}} (''specparam''): Arguments of the spec. |
| | 18 | |
| | 19 | == Properties == |
| | 20 | |
| | 21 | The following properties are defined for spec entities: |
| | 22 | |
| | 23 | * {{{name}}} (''atom''): Name of the function spec. |
| | 24 | * {{{arity}}} (''int''): Arity of the spec. |
| | 25 | * {{{text}}} (''string''): String representation of the spec. |
| | 26 | * {{{returntext}}} (''string''): String representation of the spec's return values. |
| | 27 | * {{{guardtext}}} (''string''): String representation of the spec's guards. |
| | 28 | |
| | 29 | == Textual output format == |
| | 30 | |
| | 31 | When using any of our interfaces, other than ris?, this entity will be represented in the output as a string with the same format as it was defined in the source file. |
| | 32 | |
| | 33 | {{{ |
| | 34 | ri:q("mods.spec"). |
| | 35 | a.erl |
| | 36 | -spec io_lib:format(Format :: atom() | string() | binary(), D) -> [char] when D :: list(term()). |
| | 37 | ... |
| | 38 | }}} |
| | 39 | |
| | 40 | == Review of non-trivial selectors == |
| | 41 | For some of the selectors it may not be initially clear how and what would they return. A description of these can be found here: |
| | 42 | |
| | 43 | === Spec.refmod: === |
| | 44 | Specs can have module-identifiers which determine the module whose function is being specified. This module is returned by the selector unless the module-identifier was omitted, in which case the defining module is returned. |
| | 45 | {{{ |
| | 46 | ri:q("mods.spec.refmod"). |
| | 47 | -spec io_lib:format(Format :: atom() | string() | binary(), D) -> [char] when D :: list(term()). |
| | 48 | io_lib |
| | 49 | ... |
| | 50 | }}} |
| | 51 | |
| | 52 | === Spec.arguments: === |
| | 53 | Returns the type expression for the arguments of the specification. Argument-names are included. |
| | 54 | {{{ |
| | 55 | ri:q("mods.spec.args"). |
| | 56 | -spec io_lib:format(Format :: atom() | string() | binary(), D) -> [char] when D :: list(term()). |
| | 57 | Format :: atom() | string() | binary() |
| | 58 | D |
| | 59 | ... |
| | 60 | }}} |
| | 61 | |
| | 62 | === Spec.guardtypes: === |
| | 63 | Returns the type expressions of spec-guards. |
| | 64 | {{{ |
| | 65 | ri:q("mods.spec.guardtypes"). |
| | 66 | -spec io_lib:format(Format :: atom() | string() | binary(), D) -> [char] when D :: list(term()). |
| | 67 | D :: list(term()) |
| | 68 | ... |
| | 69 | }}} |
