[ library(source_processor) | Reference Manual | Alphabetic Index ]

# source_read(+SourcePos, -NextPos, -Kind, -SourceTerm)

Read the next term from an open ECLiPSe source file

SourcePos
  Source position handle
NextPos
  Source position handle
Kind
  kind of source term (atom)
SourceTerm
  a source_term structure

## Description

This reads the next source term from a source file previously opened with source_open/3. The term at the current source position SourcePos is read, and the next source position is returned for use in subsequent source_read/4 invocations (it is not possible to read twice from the same source position!).

The term that has been read is classified into one of the following categories (Kind):

handled_directive
  A directive (a term with functor :-/1) which has already been handled (interpreted by source_read/4). Such directives are: module/1,3, local/1, export/1, reexport/1, use_module/1, lib/1, pragma/1, include/1, ./2, op/3, meta_attribute/2 and comment(include,...)
directive
  A directive (a term with functor :-/1) which has not been handled (ignored by source_read/4)
query
  A query (a term with functor ?-/1)
clause
  Any other structure, list or atom (usually a clause)
var
  A term consisting of only a variable (very likely an error)
other
  A number, string, etc (very likely an error)
comment
  Spacing, layout and comments between source terms (only when keep_comments option is in effect)
end_include
  The end of an included source file
end
  The end of the (top-level) source file

The information about the source term itself is returned as a structure

        :- export struct(source_term(
    	term,		% the read term itself
    	vars,		% list of [VarName|Var] pairs (as in readvar/3)
    	annotated       % the read term with type and source annotations
    	...
        )).

For category 'comment', the term is a string containing the comment. For category 'end' and 'end_include', the term is the atom end_of_file. In all these cases, vars is the empty list, and annotated is uninstantiated.

Note that either the vars-field or the annotated field is valid, depending on the setting of the with_annotations-option. If the option is set, the vars field contains an empty list, and the annotated term is in the same format as that returned by read_annotated/2, i.e. a recursive wrapper structure around the read term of the following format:

        :- export struct(annotated_term(
            term,                   % var, atomic or compound
                                    % args of compound terms are annotated
            type,                   % term type (see below)
            file,                   % file name (atom)
            line,                   % line number (integer >= 1)
            from, to                % source position (integers >= 0)
            ...
        )).

If the with_annotations-option is not set, the annotated-field remains uninstantiated, and the vars-field is a list as detailed in readvar/3.

Notes on module handling: When source_read/4 encounters a module-directive (which is a handled_directive), the corresponding module is implicitly created (unless it exists already, in which case it is either reused or erased and re-created, depending on the setting of the recreate_modules option), and that module becomes the context module for any subsequently read clauses or directives. By default, source_close/2 removes these modules again in order to restore the original state.

## See Also

source_open / 3, source_close / 2, readvar / 3, read_annotated / 2