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

# source_open(+File, +OptionList, -SourcePos)

Open an ECLiPSe source code file for subsequent processing

File
  Name of source file (Atom or string), or term of the form stream(Stream)
OptionList
  List of options, possibly empty
SourcePos
  Source position handle

## Description

This predicates opens an ECLiPSe source file (or prepares and already opened stream) for subsequent reading with source_read/4. Compared to the standard primitives for reading from a file, this takes care of

- nesting of included files
- creating and keeping track of modules
- syntax settings
- comments (optional)
- changing the current directory to the opened file's directory
- handling of if-elif-else-endif directives

OptionList can contain the following:

keep_comments
  treat comments and spacing between source terms as data rather than ignoring it
include_comment_files
  interpret the comment(include,Files) directive and include the contents of the given files, identical to an include(Files) directive. By default, these directives are ignored.
ignore_conditionals
  Ignore any special meaning of conditional directives (if/1, elif/1, else/0, endif/0) and just return them as a source term. The default is to interpret these directives, including or excluding corresponding source parts accordingly, while removing the directives themselves
with_annotations
  return an annotated source term with every source term (and do not return a separate variable list)
no_macro_expansion
  do not expand term macros (e.g. with/2 and of/2)
minimal_macro_expansion
  do not expand term macros except in :- directives
no_clause_expansion
  do not expand clause macros (e.g. DCGs)
goal_expansion
  do inline expansion of goals (only works if clause expansion is not disabled)
recreate_modules
  erase and re-create module when encountering a module directive

source_open/3 and source_read/4 maintain a 'current source position', which is a structure containing (among others) the following fields:

        :- export struct(source_position(
    	stream,			% Eclipse stream
    	file,			% canonical file name
    	line,			% integer
    	offset,			% integer
    	included_from,		% source_position or []
    	module,			% current source module
    	...
        )).

i.e. information about the module context and the precise location of a source term (e.g. for error messages).

If File is of the form stream(Stream), then the predicate expects Stream to be an already opened input stream. Correspondingly, the processed stream will not be closed at the end of source processing (unlike files).

### Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

## See Also

source_close / 2, source_read / 4