@ciao-lang/ts-ciao-interface

<!DOCTYPE HTML><html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#273f79"/><link rel="stylesheet" href="lpdoc.css" type="text/css"/><script type="text/javascript" src="lpdoc.js"></script><title>Basic file/stream handling — The Ciao System v1.22</title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton">☰</a><div id="sidebar" class="lpdoc-sidebar"><div style="height: 40px; margin-left: auto; margin-right: auto"><img src="ciao-logo_autofig.png" width=auto height=100%></div><div class="lpdoc-nav"><a class="lpdoc-navbutton" href="streams.html">↑</a><a class="lpdoc-navbutton" href="streams.html">←</a><a class="lpdoc-navbutton" href="io_basic.html">→</a><a class="lpdoc-navbutton" href="ciaosearch.html">🔍</a><a href="ciaofulltoc.html">TOC</a></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="ciao.html">The Ciao System</a> » </li><li><a href="StdLibs.html">PART VII - Standard libraries</a> » </li><li><a href="streams.html">Stream handling and operations</a> » </li><li><a href="">Basic file/stream handling</a></li></ul><hr></hr>ON THIS PAGE<ul><li><a href="#Usage and interface">Usage and interface</a></li><li><a href="#Documentation on exports">Documentation on exports</a></li><li><a href="#Documentation on multifiles">Documentation on multifiles</a></li><li><a href="#Documentation on imports">Documentation on imports</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Basic file/stream handling</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#stream_basic"></a> Author(s): <a class="lpdoc-idx-anchor" id="Daniel Cabeza" href="ciaosearch.html#Daniel Cabeza">Daniel Cabeza</a>, <a class="lpdoc-idx-anchor" id="Mats Carlsson" href="ciaosearch.html#Mats Carlsson">Mats Carlsson</a>. This module provides basic predicates for handling files and streams, in order to make input/output on them. <div id="Usage and interface"><h2>Usage and interface</h2><div class="lpdoc-cartouche"><ul><li>Library usage: <tt>:- use_module(engine(stream_basic)).</tt><li>Exports: <ul class="lpdoc-itemize-minus"><li>Predicates: <a class="lpdoc-idx-anchor" id="0" href="#open/3"><tt>open/3</tt></a>, <a class="lpdoc-idx-anchor" id="1" href="iso_incomplete.html#open/4"><tt>open/4</tt></a>, <a class="lpdoc-idx-anchor" id="2" href="iso_incomplete.html#close/1"><tt>close/1</tt></a>, <a class="lpdoc-idx-anchor" id="3" href="iso_incomplete.html#set_input/1"><tt>set_input/1</tt></a>, <a class="lpdoc-idx-anchor" id="4" href="#current_input/1"><tt>current_input/1</tt></a>, <a class="lpdoc-idx-anchor" id="5" href="iso_incomplete.html#set_output/1"><tt>set_output/1</tt></a>, <a class="lpdoc-idx-anchor" id="6" href="#current_output/1"><tt>current_output/1</tt></a>, <a class="lpdoc-idx-anchor" id="7" href="#character_count/2"><tt>character_count/2</tt></a>, <a class="lpdoc-idx-anchor" id="8" href="#line_count/2"><tt>line_count/2</tt></a>, <a class="lpdoc-idx-anchor" id="9" href="#line_position/2"><tt>line_position/2</tt></a>, <a class="lpdoc-idx-anchor" id="10" href="#flush_output/1"><tt>flush_output/1</tt></a>, <a class="lpdoc-idx-anchor" id="11" href="#flush_output/0"><tt>flush_output/0</tt></a>, <a class="lpdoc-idx-anchor" id="12" href="#clearerr/1"><tt>clearerr/1</tt></a>, <a class="lpdoc-idx-anchor" id="13" href="#current_stream/3"><tt>current_stream/3</tt></a>, <a class="lpdoc-idx-anchor" id="14" href="#stream_code/2"><tt>stream_code/2</tt></a>, <a class="lpdoc-idx-anchor" id="15" href="iso_incomplete.html#absolute_file_name/2"><tt>absolute_file_name/2</tt></a>, <a class="lpdoc-idx-anchor" id="16" href="#absolute_file_name/7"><tt>absolute_file_name/7</tt></a>, <a class="lpdoc-idx-anchor" id="17" href="#pipe/2"><tt>pipe/2</tt></a>, <a class="lpdoc-idx-anchor" id="18" href="#fixed_absolute_file_name/3"><tt>fixed_absolute_file_name/3</tt></a>. <li>Regular Types: <a class="lpdoc-idx-anchor" id="19" href="#open_option_list/1"><tt>open_option_list/1</tt></a>, <a class="lpdoc-idx-anchor" id="20" href="#sourcename/1"><tt>sourcename/1</tt></a>, <a class="lpdoc-idx-anchor" id="21" href="#stream/1"><tt>stream/1</tt></a>, <a class="lpdoc-idx-anchor" id="22" href="#stream_alias/1"><tt>stream_alias/1</tt></a>, <a class="lpdoc-idx-anchor" id="23" href="#io_mode/1"><tt>io_mode/1</tt></a>, <a class="lpdoc-idx-anchor" id="24" href="#atm_or_int/1"><tt>atm_or_int/1</tt></a>. <li>Multifiles: <a class="lpdoc-idx-anchor" id="25" href="#file_search_path/2"><tt>file_search_path/2</tt></a>, <a class="lpdoc-idx-anchor" id="26" href="#library_directory/1"><tt>library_directory/1</tt></a>. </ul></ul></div></div><div id="Documentation on exports"><h2>Documentation on exports</h2><div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="open/3" href="ciaosearch.html#open/3">open/3</a></div><div class="lpdoc-deftext"><tt>open(File,Mode,Stream)</tt> Open File with mode Mode and return in Stream the stream associated with the file. No extension is implicit in File.Usage 1:ISO Normal use.<ul class="lpdoc-itemize-minus"><li>Call and exit should be compatible with: (<a class="lpdoc-idx-anchor" id="27" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="28" href="#sourcename/1"><tt>stream_basic:sourcename/1</tt></a>)File is a source name. (<a class="lpdoc-idx-anchor" id="29" href="#io_mode/1"><tt>stream_basic:io_mode/1</tt></a>)Mode is an opening mode ('read', 'write' or 'append'). <li>The following properties should hold upon exit: (<a class="lpdoc-idx-anchor" id="30" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties should hold globally: (<a class="lpdoc-idx-anchor" id="31" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul>Usage 2:In the special case that File is an integer, it is assumed to be a file descriptor passed to Prolog from a foreign function call. The file descriptor is connected to a Prolog stream (invoking the C POSIX function <tt>fdopen()</tt>) which is unified with Stream.<ul class="lpdoc-itemize-minus"><li>Call and exit should be compatible with: (<a class="lpdoc-idx-anchor" id="32" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="33" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)File is an integer. (<a class="lpdoc-idx-anchor" id="34" href="#io_mode/1"><tt>stream_basic:io_mode/1</tt></a>)Mode is an opening mode ('read', 'write' or 'append'). <li>The following properties should hold upon exit: (<a class="lpdoc-idx-anchor" id="35" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="open/4" href="ciaosearch.html#open/4">open/4</a></div><div class="lpdoc-deftext"><tt>open(File,Mode,Stream,Options)</tt> Same as <tt>open(File, Mode, Stream)</tt> with options Options. See the definition of <a class="lpdoc-idx-anchor" id="36" href="#open_option_list/1"><tt>open_option_list/1</tt></a> for details.Usage:<ul class="lpdoc-itemize-minus"><li>Call and exit should be compatible with: (<a class="lpdoc-idx-anchor" id="37" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="38" href="#sourcename/1"><tt>stream_basic:sourcename/1</tt></a>)File is a source name. (<a class="lpdoc-idx-anchor" id="39" href="#io_mode/1"><tt>stream_basic:io_mode/1</tt></a>)Mode is an opening mode ('read', 'write' or 'append'). (<a class="lpdoc-idx-anchor" id="41" href="#open_option_list/1"><tt>stream_basic:open_option_list/1</tt></a>)Options is a list of options for <a class="lpdoc-idx-anchor" id="40" href="iso_incomplete.html#open/4"><tt>open/4</tt></a>. <li>The following properties should hold upon exit: (<a class="lpdoc-idx-anchor" id="42" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties should hold globally: (<a class="lpdoc-idx-anchor" id="43" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">REGTYPE<a class="lpdoc-idx-anchor" id="open_option_list/1" href="ciaosearch.html#open_option_list/1">open_option_list/1</a></div><div class="lpdoc-deftext">A list of options for <a class="lpdoc-idx-anchor" id="44" href="iso_incomplete.html#open/4"><tt>open/4</tt></a>, currently the meaningful options are:<dl> <dt><tt>lock</tt><dd> Try to set an advisory lock for the file. If the open mode is <tt>read</tt>, the lock is a read (shared) lock, else it is a write (exclusive) lock. If the lock cannot be acquired, the call waits until it is released (but can fail in exceptional cases).<dt><tt>lock_nb</tt><dd> Same as <tt>lock</tt>, but the call immediately fails if the lock cannot be acquired.<dt><tt>lock(Lock_Mode)</tt><dd> Same as <tt>lock</tt>, but specifying in <tt>Lock_Mode</tt> whether the lock is <tt>read</tt> (also <tt>shared</tt>) or <tt>write</tt> (also <tt>exclusive</tt>). This option has be included for compatibility with the SWI-Prolog locking options, because in general the type of lock should match the open mode as in the <tt>lock</tt> option.<dt><tt>lock_nb(Lock_Mode)</tt><dd> Same as the previous option but with the <tt>lock_nb</tt> behavior.</dl> All file locking is implemented via the POSIX function fcntl(). Please refer to its manual page for details.Usage:<tt>open_option_list(L)</tt> L is a list of options for <a class="lpdoc-idx-anchor" id="45" href="iso_incomplete.html#open/4"><tt>open/4</tt></a>.<ul class="lpdoc-itemize-minus"></ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="close/1" href="ciaosearch.html#close/1">close/1</a></div><div class="lpdoc-deftext"><tt>close(Stream)</tt> Close the stream Stream.Usage:ISO <ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="46" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="47" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="48" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="set_input/1" href="ciaosearch.html#set_input/1">set_input/1</a></div><div class="lpdoc-deftext"><tt>set_input(Stream)</tt> Set the current input stream to Stream. A notion of <a class="lpdoc-idx-anchor" id="49" href="ciaosearch.html#current input stream">current input stream</a> is maintained by the system, so that input predicates with no explicit stream operate on the current input stream. Initially it is set to <tt>user_input</tt>.Usage:ISO <ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="50" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="51" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="52" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="current_input/1" href="ciaosearch.html#current_input/1">current_input/1</a></div><div class="lpdoc-deftext"><tt>current_input(Stream)</tt> Unify Stream with the <a class="lpdoc-idx-anchor" id="53" href="ciaosearch.html#current input stream">current input stream</a>. In addition to the ISO behavior, stream aliases are allowed. This is useful for most applications checking whether a stream is the standard input or output.Usage:ISO <ul class="lpdoc-itemize-minus"><li>Calls should, and exit will be compatible with: (<a class="lpdoc-idx-anchor" id="54" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="55" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="56" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="set_output/1" href="ciaosearch.html#set_output/1">set_output/1</a></div><div class="lpdoc-deftext"><tt>set_output(Stream)</tt> Set the current output stream to Stream. A notion of <a class="lpdoc-idx-anchor" id="57" href="ciaosearch.html#current output stream">current output stream</a> is maintained by the system, so that output predicates with no explicit stream operate on the current output stream. Initially it is set to <tt>user_output</tt>.Usage:ISO <ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="58" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="59" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="current_output/1" href="ciaosearch.html#current_output/1">current_output/1</a></div><div class="lpdoc-deftext"><tt>current_output(Stream)</tt> Unify Stream with the <a class="lpdoc-idx-anchor" id="60" href="ciaosearch.html#current output stream">current output stream</a>. The same comment as for <a class="lpdoc-idx-anchor" id="61" href="#current_input/1"><tt>current_input/1</tt></a> applies.Usage:ISO <ul class="lpdoc-itemize-minus"><li>Calls should, and exit will be compatible with: (<a class="lpdoc-idx-anchor" id="62" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="63" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="64" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="character_count/2" href="ciaosearch.html#character_count/2">character_count/2</a></div><div class="lpdoc-deftext"><tt>character_count(Stream,Count)</tt> Count characters have been read from or written to Stream.Usage:<ul class="lpdoc-itemize-minus"><li>Calls should, and exit will be compatible with: (<a class="lpdoc-idx-anchor" id="65" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Count is an integer. <li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="66" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="67" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Count is an integer. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="68" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="line_count/2" href="ciaosearch.html#line_count/2">line_count/2</a></div><div class="lpdoc-deftext"><tt>line_count(Stream,Count)</tt> Count lines have been read from or written to Stream.Usage:<ul class="lpdoc-itemize-minus"><li>Calls should, and exit will be compatible with: (<a class="lpdoc-idx-anchor" id="69" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Count is an integer. <li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="70" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="71" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Count is an integer. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="72" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="line_position/2" href="ciaosearch.html#line_position/2">line_position/2</a></div><div class="lpdoc-deftext"><tt>line_position(Stream,Count)</tt> Count characters have been read from or written to the current line of Stream.Usage:<ul class="lpdoc-itemize-minus"><li>Calls should, and exit will be compatible with: (<a class="lpdoc-idx-anchor" id="73" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Count is an integer. <li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="74" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="75" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)Count is an integer. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="76" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="flush_output/1" href="ciaosearch.html#flush_output/1">flush_output/1</a></div><div class="lpdoc-deftext"><tt>flush_output(Stream)</tt> Flush any buffered data to output stream Stream.Usage:ISO <ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="77" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="78" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="79" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="flush_output/0" href="ciaosearch.html#flush_output/0">flush_output/0</a></div><div class="lpdoc-deftext"><tt>flush_output</tt> Behaves like <tt>current_output(S), flush_output(S)</tt></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="clearerr/1" href="ciaosearch.html#clearerr/1">clearerr/1</a></div><div class="lpdoc-deftext"><tt>clearerr(Stream)</tt> Clear the end-of-file and error indicators for input stream Stream.Usage:<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="80" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="81" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="current_stream/3" href="ciaosearch.html#current_stream/3">current_stream/3</a></div><div class="lpdoc-deftext"><tt>current_stream(Filename,Mode,Stream)</tt> Stream is a stream which was opened in mode Mode and which is connected to the absolute file name Filename (an atom) or to the file descriptor Filename (an integer). This predicate can be used for enumerating all currently open streams through backtracking.Usage:<ul class="lpdoc-itemize-minus"><li>Calls should, and exit will be compatible with: (<a class="lpdoc-idx-anchor" id="83" href="#atm_or_int/1"><tt>stream_basic:atm_or_int/1</tt></a>)<a class="lpdoc-idx-anchor" id="82" href="ciaosearch.html#atm_or_int(Filename)"><tt>stream_basic:atm_or_int(Filename)</tt></a> (<a class="lpdoc-idx-anchor" id="84" href="#io_mode/1"><tt>stream_basic:io_mode/1</tt></a>)Mode is an opening mode ('read', 'write' or 'append'). (<a class="lpdoc-idx-anchor" id="85" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="87" href="#atm_or_int/1"><tt>stream_basic:atm_or_int/1</tt></a>)<a class="lpdoc-idx-anchor" id="86" href="ciaosearch.html#atm_or_int(Filename)"><tt>stream_basic:atm_or_int(Filename)</tt></a> (<a class="lpdoc-idx-anchor" id="88" href="#io_mode/1"><tt>stream_basic:io_mode/1</tt></a>)Mode is an opening mode ('read', 'write' or 'append'). (<a class="lpdoc-idx-anchor" id="89" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="90" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="stream_code/2" href="ciaosearch.html#stream_code/2">stream_code/2</a></div><div class="lpdoc-deftext"><tt>stream_code(Stream,StreamCode)</tt> StreamCode is the file descriptor (an integer) corresponding to the Prolog stream Stream.Usage 1:<ul class="lpdoc-itemize-minus"><li>Calls should, and exit will be compatible with: (<a class="lpdoc-idx-anchor" id="91" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)StreamCode is an integer. <li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="92" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="93" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)StreamCode is an integer. </ul>Usage 2:<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="94" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)Stream is a free variable. (<a class="lpdoc-idx-anchor" id="95" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)StreamCode is an integer. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="96" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Stream is an open stream. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="absolute_file_name/2" href="ciaosearch.html#absolute_file_name/2">absolute_file_name/2</a></div><div class="lpdoc-deftext"><tt>absolute_file_name(RelFileSpec,AbsFileSpec)</tt> If RelFileSpec is an absolute pathname then do an absolute lookup. If RelFileSpec is a relative pathname then prefix the name with the name of the current directory and do an absolute lookup. If RelFileSpec is a path alias, perform the lookup following the path alias rules (see <a class="lpdoc-idx-anchor" id="97" href="#sourcename/1"><tt>sourcename/1</tt></a>). In all cases: if a matching file with suffix <tt>.pl</tt> exists, then AbsFileSpec will be unified with this file. Failure to open a file normally causes an exception. The behaviour can be controlled by the <tt>fileerrors</tt> <a class="lpdoc-idx-anchor" id="98" href="ciaosearch.html#prolog flag">prolog flag</a>.Usage:<tt>absolute_file_name(RelFileSpec,AbsFileSpec)</tt> AbsFileSpec is the absolute name (with full path) of RelFileSpec.<ul class="lpdoc-itemize-minus"><li>Call and exit should be compatible with: (<a class="lpdoc-idx-anchor" id="99" href="#sourcename/1"><tt>stream_basic:sourcename/1</tt></a>)RelFileSpec is a source name. (<a class="lpdoc-idx-anchor" id="100" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)AbsFileSpec is an atom. <li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="101" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)RelFileSpec is currently a term which is not a free variable. (<a class="lpdoc-idx-anchor" id="102" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)AbsFileSpec is a free variable. <li>The following properties should hold globally: (<a class="lpdoc-idx-anchor" id="103" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="absolute_file_name/7" href="ciaosearch.html#absolute_file_name/7">absolute_file_name/7</a></div><div class="lpdoc-deftext"><tt>absolute_file_name(Spec,Opt,Suffix,CurrDir,AbsFile,AbsBase,AbsDir)</tt> AbsFile is the absolute name (with full path) of Spec, which has an optional first suffix Opt and an optional second suffix Suffix, when the current directory is CurrDir. AbsBase is the same as AbsFile, but without the second suffix, and AbsDir is the absolute path of the directory where AbsFile is. The Ciao compiler invokes this predicate with Opt=<tt>'_opt'</tt> and Suffix=<tt>'.pl'</tt> when searching source files.Usage:<ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="104" href="#sourcename/1"><tt>stream_basic:sourcename/1</tt></a>)Spec is a source name. (<a class="lpdoc-idx-anchor" id="105" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)Opt is an atom. (<a class="lpdoc-idx-anchor" id="106" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)Suffix is an atom. (<a class="lpdoc-idx-anchor" id="107" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)CurrDir is an atom. (<a class="lpdoc-idx-anchor" id="108" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)AbsFile is a free variable. (<a class="lpdoc-idx-anchor" id="109" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)AbsBase is a free variable. (<a class="lpdoc-idx-anchor" id="110" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)AbsDir is a free variable. <li>The following properties should hold upon exit: (<a class="lpdoc-idx-anchor" id="111" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)AbsFile is an atom. (<a class="lpdoc-idx-anchor" id="112" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)AbsBase is an atom. (<a class="lpdoc-idx-anchor" id="113" href="basic_props.html#atm/1"><tt>basic_props:atm/1</tt></a>)AbsDir is an atom. <li>The following properties should hold globally: (<a class="lpdoc-idx-anchor" id="114" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="pipe/2" href="ciaosearch.html#pipe/2">pipe/2</a></div><div class="lpdoc-deftext">Usage:ISO <ul class="lpdoc-itemize-minus"><li>The following properties should hold at call time: (<a class="lpdoc-idx-anchor" id="115" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)Arg1 is a free variable. (<a class="lpdoc-idx-anchor" id="116" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)Arg2 is a free variable. <li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="117" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Arg1 is an open stream. (<a class="lpdoc-idx-anchor" id="118" href="#stream/1"><tt>stream_basic:stream/1</tt></a>)Arg2 is an open stream. <li>The following properties hold globally: (<a class="lpdoc-idx-anchor" id="119" href="basic_props.html#native/1"><tt>basic_props:native/1</tt></a>)This predicate is understood natively by CiaoPP. </ul></div></div> <div><div class="lpdoc-defname">REGTYPE<a class="lpdoc-idx-anchor" id="sourcename/1" href="ciaosearch.html#sourcename/1">sourcename/1</a></div><div class="lpdoc-deftext">A source name is a flexible way of referring to a concrete file. A source name is either a relative or absolute filename given as:<ul> <li>an atom, or<li>a unary functor (which represents a <a class="lpdoc-idx-anchor" id="120" href="ciaosearch.html#path alias">path alias</a>, see below) applied to a relative path, the latter being given as an atom.</ul> In all cases certain filename extensions (e.g., <tt>.pl</tt>) can be implicit. In the first form above, file names can be relative to the current directory. Also, file names beginning with <tt>~</tt> or <tt>$</tt> are treated specially. For example,<dl> <dt><tt>'~/ciao/sample.pl'</tt><dd> is equivalent to <tt>'/home/staff/herme/ciao/sample.pl'</tt>, if <tt>/home/staff/herme</tt> is the user's home directory. (On POSIX systems, this is equivalent to <tt>'$HOME/ciao/sample.pl'</tt> as explained below.)<dt><tt>'~bardo/prolog/sample.pl'</tt><dd> is equivalent to <tt>'/home/bardo/prolog/sample.pl'</tt>, if <tt>/home/bardo</tt> is <tt>bardo</tt>'s home directory.<dt><tt>'$UTIL/sample.pl'</tt><dd> is equivalent to <tt>'/usr/local/src/utilities/sample.pl'</tt>, if <tt>/usr/local/src/utilities</tt> is the value of the environment variable <tt>UTIL</tt>.</dl> The second form allows using path aliases. Such aliases allow refering to files not with absolute file system paths but with paths which are relative to predefined (or user-defined) abstract names. For example, given the path alias <tt>myutils</tt> which has been defined to refer to path <tt>'/home/bardo/utilities'</tt>, if that directory contains the file <tt>stuff.pl</tt> then the term <tt>myutils(stuff)</tt> in a <a class="lpdoc-idx-anchor" id="121" href="toplevel_doc.html#use_module/1"><tt>use_module/1</tt></a> declaration would refer to the file <tt>'/home/bardo/utilities/stuff.pl'</tt> (the <tt>.pl</tt> extension is implicit in the <a class="lpdoc-idx-anchor" id="122" href="toplevel_doc.html#use_module/1"><tt>use_module/1</tt></a> declaration). As a special case, if that directory contains a subdirectory named <tt>stuff</tt> which in turn contains the file <tt>stuff.pl</tt>, the same term would refer to the file <tt>'/home/bardo/utilities/stuff/stuff.pl'</tt>. If a path alias is related to several paths, all paths are scanned in sequence until a match is found. For information on predefined path aliases or how to define new path aliases, see <a class="lpdoc-idx-anchor" id="123" href="#file_search_path/2"><tt>file_search_path/2</tt></a>. Usage:<tt>sourcename(F)</tt> F is a source name.<ul class="lpdoc-itemize-minus"></ul></div></div> <div><div class="lpdoc-defname">REGTYPE<a class="lpdoc-idx-anchor" id="stream/1" href="ciaosearch.html#stream/1">stream/1</a></div><div class="lpdoc-deftext">Streams correspond to the file pointers used at the operating system level, and usually represent opened files. There are four special streams which correspond with the operating system standard streams: <dl> <dt><tt>user_input</tt><dd> The standard input stream, i.e. the terminal, usually.<dt><tt>user_output</tt><dd> The standard output stream, i.e. the terminal, usually.<dt><tt>user_error</tt><dd> The standard error stream.<dt><tt>user</tt><dd> The standard input or output stream, depending on context.</dl> Usage:<tt>stream(S)</tt> S is an open stream.<ul class="lpdoc-itemize-minus"></ul></div></div> <div><div class="lpdoc-defname">REGTYPE<a class="lpdoc-idx-anchor" id="stream_alias/1" href="ciaosearch.html#stream_alias/1">stream_alias/1</a></div><div class="lpdoc-deftext">Usage:<tt>stream_alias(S)</tt> S is the alias of an open stream, i.e., an atom which represents a stream at Prolog level.<ul class="lpdoc-itemize-minus"></ul></div></div> <div><div class="lpdoc-defname">REGTYPE<a class="lpdoc-idx-anchor" id="io_mode/1" href="ciaosearch.html#io_mode/1">io_mode/1</a></div><div class="lpdoc-deftext">Can have the following values: <dl> <dt><tt>read</tt><dd> Open the file for input.<dt><tt>write</tt><dd> Open the file for output. The file is created if it does not already exist, the file will otherwise be truncated.<dt><tt>append</tt><dd> Open the file for output. The file is created if it does not already exist, the file will otherwise be appended to.</dl>Usage:<tt>io_mode(M)</tt> M is an opening mode ('read', 'write' or 'append').<ul class="lpdoc-itemize-minus"></ul></div></div> <div><div class="lpdoc-defname">REGTYPE<a class="lpdoc-idx-anchor" id="atm_or_int/1" href="ciaosearch.html#atm_or_int/1">atm_or_int/1</a></div><div class="lpdoc-deftext">A regular type, defined as follows:<pre class="lpdoc-codeblock">atm_or_int(X) :- atm(X). atm_or_int(X) :- int(X). </pre> </div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="fixed_absolute_file_name/3" href="ciaosearch.html#fixed_absolute_file_name/3">fixed_absolute_file_name/3</a></div><div class="lpdoc-deftext">No further documentation available for this predicate.</div></div> </div><div id="Documentation on multifiles"><h2>Documentation on multifiles</h2><div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="file_search_path/2" href="ciaosearch.html#file_search_path/2">file_search_path/2</a></div><div class="lpdoc-deftext"><tt>file_search_path(Alias,Path)</tt> The <a class="lpdoc-idx-anchor" id="124" href="ciaosearch.html#path alias">path alias</a> Alias is linked to path Path. Both arguments must be atoms. New facts (or clauses) of this predicate can be asserted to define new path aliases. Predefined path aliases in Ciao are:<dl> <dt><tt>library</tt><dd> Initially points to all Ciao library paths. See <a class="lpdoc-idx-anchor" id="125" href="#library_directory/1"><tt>library_directory/1</tt></a>.<dt><tt>engine</tt><dd> The path of the <a class="lpdoc-idx-anchor" id="126" href="ciaosearch.html#Ciao engine builtins">Ciao engine builtins</a>.<dt><tt>.</tt><dd> The current path (<tt>'.'</tt>).</dl> The predicate is multifile. The predicate is of type dynamic. <tt>file_search_path(X,Y)</tt> <ul class="lpdoc-itemize-minus"><li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="127" href="basic_props.html#gnd/1"><tt>basic_props:gnd/1</tt></a>)X is ground. (<a class="lpdoc-idx-anchor" id="128" href="basic_props.html#gnd/1"><tt>basic_props:gnd/1</tt></a>)Y is ground. </ul></div></div> <div><div class="lpdoc-defname">PREDICATE<a class="lpdoc-idx-anchor" id="library_directory/1" href="ciaosearch.html#library_directory/1">library_directory/1</a></div><div class="lpdoc-deftext"><tt>library_directory(Path)</tt> Path is a library path (a path represented by the <a class="lpdoc-idx-anchor" id="129" href="ciaosearch.html#path alias">path alias</a> <tt>library</tt>). More library paths can be defined by asserting new facts (or clauses) of this predicate. The predicate is multifile. The predicate is of type dynamic. <tt>library_directory(X)</tt> <ul class="lpdoc-itemize-minus"><li>The following properties hold upon exit: (<a class="lpdoc-idx-anchor" id="130" href="basic_props.html#gnd/1"><tt>basic_props:gnd/1</tt></a>)X is ground. </ul></div></div> </div><div id="Documentation on imports"><h2>Documentation on imports</h2>This module has the following direct dependencies:<ul class="lpdoc-itemize-minus"><li>Packages: <a class="lpdoc-idx-anchor" id="131" href="ciaosearch.html#prelude"><tt>prelude</tt></a>, <a class="lpdoc-idx-anchor" id="132" href="ciaosearch.html#initial"><tt>initial</tt></a>, <a class="lpdoc-idx-anchor" id="133" href="condcomp_doc.html"><tt>condcomp</tt></a>, <a class="lpdoc-idx-anchor" id="134" href="assertions_doc.html"><tt>assertions</tt></a>, <a class="lpdoc-idx-anchor" id="135" href="ciaos