This module provides a number of meta-predicates for directing the input or output streams of arbitrary goals from or to files or streams. It also provides some predicates for finding files in the file system, and for matching files on the basis of extension.

Types

What follows is a half-baked scheme for assigning types to things like search paths and file names.

First, a path is an atom that can be interpreted as a legal path in the file system, either relative or absolute. Next path(file) is a path that leads to a file and path(dir) is a path that leads to a directory.

A pattern is an atom that can be understood by expand_file_name/2 and expanded to a legal path. Thus, it can include wildcards "*?[]{}", environment variables "$var" and "~", which is equivalent to "$HOME". Thus, the type of expand_file_name/2 is pred(+pattern, -path).

A spec(T) is a term that can be expanded by expand_file_search_path/2 to produce an atom of type T. So, spec(pattern) expands to a pattern, and spec(path(file)) expands to a file name. The type of expand_file_search_path/2 is pred(+spec(T), -T).

Then, for finding files, we have:

findspec ---> in(spec(pattern), pattern)
            ; in(spec(pattern))
            ; under(spec(pattern), pattern)
            ; under(spec(pattern))
            ; like(spec(pattern)).

To be done

-

• Consider extending with_output_to/2 and with_input_from/2 to understand file(Filename) and file(Filename,Opts) as sources/sinks.
• Consider removing file_under/4 and providing another mechanism to obtain the path of a file as a list of directory names.
• Consider other ways to represent recursive directory search, eg double-star notation: the pattern '/a/b/ ** /c/d/f' (without spaces). Note this allows matching on arbitrary segments of the directory path.

 with_stream(+Opener:pred(-stream), +User:pred(+stream)) is semidet

Base predicate for doing things with stream. Opener is a unary predicate (ie callable with call/2) which must prepare the stream. User is a unary predicate, called with the open stream. The stream is guaranteed to be closed on exit. Eg, using the lambda library to form anonymous predicates:

with_stream(open('out.txt',write), \S^writeln(S,'Hello!')).
with_stream(open('in.txt',read), \S^read(S,T)).

 with_stream(@Stream, :Opener, :Goal) is semidet

DEPRECATED due to nasty term copying. Base predicate for doing things with stream. Opener is a goal which must prepare the stream, Stream is the variable which will hold the valid stream handle, and Goal is called with the stream open. The stream is guaranteed to be closed on exit. Stream will remain unbound on exit, but any other variables in Opener or Goal will be left in the state that Opener and Goal leave them in. The idea is that Opener and Goal share the Stream variable, eg:

with_stream( S, open('out.txt',write,S), writeln(S,'Hello!')).
with_stream( S, open('in.txt',read,S), read(S,T)).

 with_output_to_file(+File, :Goal) is semidet

 with_output_to_file(+File, :Goal, +Opts) is semidet

Call Goal redirecting output to the file File, which is opened as with open(File,write,Str) or open(File,write,Opts,Str). However, if the option mode(Mode) is present, it is removed from the list (leaving Opts1) and the file is opened as with open(File,Mode,Opts1,Str). The default mode is write.

 with_input_from_file(+File, :Goal) is semidet

 with_input_from_file(+File, :Goal, +Opts) is semidet

Call Goal redirecting output to the file File, which is opened as with open(File,write,Str) or open(File,write,Opts,Str).

 with_input_from(+Source, :Goal) is semidet

Temporarily switch current input to object specified by Source while calling Goal as in once/1. Source is a term like that supplied to with_output_to/2 and can be any of:

• A stream handle or alias.
• atom(+Atom)
• codes(+Codes)
• chars(+Chars)
• string(+String)

 read_lines(+Stream, -Lines:list(list(integer))) is semidet

Read all lines from Stream and return a list of lists of character codes.

 file_under(+Root:spec(pattern), +Pattern:pattern, -File:path(file), -RelPath:list(atom)) is nondet

Enumerate all files under directory root whose names match Pattern. Root can be a unary term as understood by expand_file_search_path/2. On exit, File is the fully qualified path to the file and RelPath is a list of directory names represented as atoms, relative to Root.

deprecated

- Consider using find_files/3 and doing without RelPath.

 file_under_dl(+Root:spec(dir), +Options:list, -File:atom, ?DirHead:list(atom), ?DirTail:list(atom)) is nondet

Finds files under directory Dir, succeeding multiple times with AbsPath bound to the absolute path (as an atom), and Parts bound to a list of directory components ending with the file name. Options can include:

abs(-AbsPath:path(file))

AbsPath is unified with the absolute path of each file found.

filter(+Filter:pred(+atom,+path(file)))

Filter is called with the name of and absolute path of each directory found. If it fails, that directory is not recursed into.

NB. this interface of this predicate is unstable and may change in future.

 find_files(+FindSpec:findspec, -File:path(file)) is nondet

General file finding predicate. FindSpec is one of:

in(DirSpec:spec(pattern), Pattern:pattern)

Looks for names matching Pattern in all directories matching DirSpec.

in(DirSpec:spec(pattern))

Equivalent to in(DirSpec,'*').

under(DirSpec:spec(pattern), Pattern:pattern)

Looks for names matching Pattern recursively under all directories matching DirSpec,

under(DirSpec:spec(pattern))

Equivalent to under(DirSpec,'*').

like(FileSpec:spec(pattern))

DirSpec is an atom or file search path term as understood by expand_file_search_path/2. It may contain wildcards as understood by expand_file_name/2, and is used to find directories. Pattern is a pattern for file names, without any directory components. FileSpec is a files search path term that is used to find files. File is unified with the absolute path of matching, readable files.

 file_under(+Root:path(dir), +Pattern:pattern, -File:path(file))// is nondet

DCG rule common to file_under/4 and find_files/2. Finds file names matching Pattern in or under Root and matches final argument pair with difference list containing the directory names along the path from the the Root to the file. File is an absolute path to the file in question.

 expand_pattern(+Pattern:pattern, -File:path) is nondet

Expands Pattern and unifies File with names of matching, readable files, exactly as expand_file_name/1, except that matches are produced one by one on backtracking, instead of all together in a list. File which the current user does not have permission to read are not returned.

 directory_entry(+Dir:path(dir), -Entry:atom) is nondet

Is true when Entry is a file or directory in the directory Dir, not including the special entries '.' and '..'.

 file_extension(+File:path, -Ext:atom) is nondet

file_extension(+File:path, +Ext:atom) is semidet

True if Filename has an extensions of Ext, where Ext does not include the dot. An extension is defined as any sequence of characters (including dots) after a dot that is not the first character of the name part of a path. Succeeds multiple times if File has multiple extensions, eg, these are all true:

file_extension('doc.ps.gz','ps.gz').
file_extension('doc.ps.gz','gz').

The predicate is case sensitive and case presevering.

 extension_in(+File:path, +Extensions:list(atom)) is semidet

True if File has one of the extensions in the list Extensions. Extensions are case insensitive. An extension is any sequence of characters following a dot in the name part of a file name.

 in_temp_dir(+Goal:callable) is semidet

Calls Goal with the current directory set to a newly created directory (using with_temp_dir/2) which is deleted after the call is finished. Goal is called as once(Goal) to ensure that the working directory is restored to its original value for any subsequent goals.

 with_temp_dir(@Dir:path, +Goal:callable) is nondet

Calls Goal with Dir bound to a new temporary directory. Once Goal is finished, the directory and its contents are deleted.

 file_modes(+File:path, +UserClass:oneof([owner,group,other]), +Action:oneof([read,write,execute]), -Legal:boolean) is det

file_modes(+File:path, -UserClass:oneof([owner,group,other]), -Action:oneof([read,write,execute]), -Legal:boolean) is multi

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 with_output_to_file(Arg1, Arg2, Arg3)

 with_input_from_file(Arg1, Arg2, Arg3)