1:- module( os_lib, [ 
    2              % name manipulators
    3              os_base/2,                 % +Os, -Bname
    4              os_ext/2,                  % ?Ext, +Os
    5              os_ext/3,                  % ?Ext, ?Stem, ?Os
    6              os_ext/4,                  % ?Ext, ?NewExt, +Os, -NewOs
    7              os_dir_stem_ext/2,         % -Os, +Opts
    8              os_dir_stem_ext/4,         % ?Dir, ?Stem, ?Ext, ?Os
    9              os_stem/3,                 % ?Stem, -Os, +Opts
   10              os_postfix/2,              % -PsfxS, +Posted
   11              os_postfix/3,              % +PsfxS, ?Fname, ?Posted
   12              os_postfix/4,              % +PsfxS, ?Fname, ?Posted, +Opts
   13              os_abs/2, os_abs/3,        % +Os, -Abs[, +Opts]
   14              os_path/2,                 % ?Parts, ?Path
   15              os_path/3,                 % +-Dir, +-File, -+Path
   16              os_slashify/2,             % +-Path, -+Slashed
   17              os_parts/2,                % +-Parts, -+Stem
   18              os_parts/3,                % +-Parts, -+Stem, +Opts
   19              os_unique/2,               % +Tkn, -Os
   20              os_unique/3,               % +Tkn, -Os, +Opts
   21
   22              % commands
   23              os_mv/2,                   % +From, +To
   24              os_cp/2,                   % +From, +To
   25              os_ln_s/2,                 % +From, +To
   26              os_rm/1, os_rm/2,          % see os_remove/1,2
   27              os_remove/1,               % +Os
   28              os_remove/2,               % +Os, +Opts
   29              os_make_path/1,            % +Os
   30              os_make_path/2,            % +Os, +Opts
   31              os_repoint/2,              % +Os, +Opts 
   32              os_mill/4,                 % +Os, +Goal, ?Milled, +Opts
   33              os_un_zip/3,               % +Os, ?Stem, +Opts
   34
   35              % helpers
   36              os_sep/1,                  % -Sep
   37              os_sep/2,                  % -Sep, +Opts
   38              os_sel/3,                  % +Oses, +Pattern, -Selected
   39              os_sel/4,                  % +Oses, +Pattern, -Selected, +Opts
   40              os_term/2,                 % +-Atom, -+SlashTerm
   41              os_name/2,                 % +Os, -Type
   42
   43              % types and casting
   44              % os_type_entity/3,         % +Os, +Type, -Typed
   45              os_cast/2,                 % +Os, -Typed
   46              os_cast/3,                 % +Type, +Os, -Typed
   47              os_tmp_dir/1,              % -Os
   48              os_type_base/2,            % ?Type, ?Base
   49              os_version/2,              % -Vers, -Date
   50              os_lib_version/2,          % -Vers, -Date
   51
   52              % logical
   53              os_exists/1, os_exists/2,  % +Os[, +Opts]
   54              os_file/1, os_file/2,      % ?Os[, +Opts]
   55              os_files/1, os_files/2,    % -Os[, +Opts]
   56              os_dir/1, os_dir/2,        % ?Os[, +Opts]
   57              os_dirs/1, os_dirs/2,      % ?Os[, +Opts]
   58
   59              % operators
   60              op( 400, fx, / )
   61            ] ).

Operating system interaction predicates.

This library collects a number of predicates useful for OS interactions. The emphasis here is on operations on files and directories rather than on calling OS commands. Unlike the system predicates of SWI/Yap here we adhere to the <lib>_ convention prefix that allows for more succinct predicate names. The assumption is that by using prefix "os", there will be a main argument that is an OS entity, so the predicate name does not have to explicitly refer to all the arguments. For instance

Highlights

polymorphic
4 ways to name OS objects
casting
and particulalry output variable casting via variable decoration
os_exists(Os, Opts)
works on files and dirs by default, and can be specialised via Opts
os_postfix(Psfx, Os, Posted)
os_postfix/3 add a bit on a OS name to produce a new one
os_ext(Ext, Stem, Os)
os_ext/3 is a renamed file_name_extension/3 with few extra bits
os_unique(Token, Os, Opts)
constructs unique filenames either based ondate (and possible time stamp) or on versioning
os_dir_stem_ext(Dir, Stem, Ext, Os)
os_dir_stem_ext/4 construct and de-construct OS names from/to its main parts
os_dir_stem_ext(Os, Opts)
construct
os_mill(File, Goal, Milled, Opts)
os_mill/4 allows construction of evolving pipelines
os_file(File)
os_file/1 backtrack over all files in current directory

In addition, the library is polymorphic in naming OS objects by supporting 4 different os term structures:

Currently the emphasis is on file name manipulations but command (eg copy_file) are likely to be included in new versions. Main reason why they are not yes, is that we use pack(by_unix).

Installation

To install

?- pack_install( os_lib ).

to load

?- use_module( library(os) ).

or

?- use_module( library(os_lib) ).

Opts

The library attempts to keep a consistent set of options that are on occasions funnelled through to either other interface or commonly used private predicates.

Common options:

dir(Dir=(.))
directory for input and output
idir(Idir=(.))
directory for input (overrides Dir)
odir(Odir=(.))
directory for output (overrides Dir)
ext(Ext=)
extension for file
stem(Stem)
stem to be used for constructing os names
sub(Sub)
apply operation recursive to sub directories

Variable name conventions

var(Os)
An os entity

Casts

(os_cast/3,os_cast/2)

\ Os
casts to /-terms
+ Os
casts to atoms
&(Os)
casts to strings
@(Os)
casts to alias (input must be an alias to start with)

Nonmeclature

Predicates

The library predicates can be split to 4 groups.

  1. Predicates for manipulating and constructing OS entity names
  2. Commands
  3. Logical
  4. Helpers

Info

author
- nicos angelopoulos
version
- 0.0.1 2015/4/30
- 0.0.2 2015/4/30 added module documentation
- 0.0.3 2015/12/10 redone the typing and added better alias support, started custom errors
- 0.1.0 2016/2/24 first publisc release
- 0.6.0 2017/3/10 works with pack(lib)
- 1.0.0 2018/3/18
- 1.2.0 2018/8/5 added os_files/1,2 and os_dirs/1,2 (with options) and removed os_dir_files/2 and os_dir_dirs/2.
- 1.3 2018/10/1 cleaner error handling via throw, new opt dots(D), os_cast/3 arguments switch
- 1.4 2019/4/22 option sub(Sub); cp_rec.pl script; list of postfixes, etc
- 1.5 2019/4/22 os_path/2, fixes and new options to os_mill/4 ; os_exists/2 (return type) & os_sel/4
- 1.6 2022/6/14 fixed: os_exist( file, type(link) ), added option read_link(RLnk) to os_file/2
- 1.7 2024/2/7 fixes in: os_unique/3 and os_ext/4
- 2.0 2025/12/7 intro succ() opt in os_exists/2; os_lib_version/2
See also
- http://www.stoics.org.uk/~nicos/sware/os
- http://www.stoics.org.uk/~nicos/sware/os/html/os_lib.html
- doc/Releases.txt
To be done
- os_pwd/1 (working_directory + casting)
- use os_path/3 as a template to convert all lib predicates to castable outputs.
- there might a bit of dead code around

*/

  243:- use_module(library(lists)).      % select/3,...
  244:- use_module(library(apply)).      % maplist/3,...
  245:- use_module(library(date)).       % date_time_value/3.
  246:- use_module(library(debug)).      % /1,3.  -> switch to debuc/1,3
  247:- use_module(library(filesex)).    % link_file/3, make_directory_path/1.
  248:- use_module(library(prolog_source)).    % file_alias_path/2.
  249
  250:- use_module(library(lib)).  251:- lib(source(os_lib), homonyms(true)).  252
  253:- lib(options).  254:- lib(pack_errors).  255
  256:- lib(os_dir_stem_ext/2).  257:- lib(os_dir_stem_ext/4).  258:- lib(os_stem/3).  259:- lib(os_ext/2).  260:- lib(os_ext/3).  261:- lib(os_ext/4).  262:- lib(os_rm/1).  263:- lib(os_rm/2).  264:- lib(os_remove/1).  265:- lib(os_remove/2).  266:- lib(os_make_path/1).  267:- lib(os_make_path/2).  268:- lib(os_mill/4).  269:- lib(os_un_zip/3).  270:- lib(os_parts/2).  271:- lib(os_parts/3).  272:- lib(os_path/2).  273:- lib(os_path/3).  274:- lib(os_postfix/2).  275:- lib(os_postfix/3).  276:- lib(os_postfix/4).  277:- lib(os_repoint/2).  278:- lib(os_slashify/2).  279:- lib(os_term/2).  280:- lib(os_tmp_dir/1).  281:- lib(os_name/2).  282:- lib(os_unique/2).  283:- lib(os_unique/3).  284:- lib(os_base/2).  285:- lib(os_cast/2).  286:- lib(os_cast/3).  287:- lib(os_errors/0).  288:- lib(os_abs/2).  289:- lib(os_abs/3).  290:- lib(os_file/1).  291:- lib(os_file/2).  292:- lib(os_files/1).  293:- lib(os_files/2).  294:- lib(os_dir/1).  295:- lib(os_dir/2).  296:- lib(os_dirs/1).  297:- lib(os_dirs/2).  298:- lib(os_exists/1).  299:- lib(os_exists/2).  300:- lib(os_sep/1).  301:- lib(os_sep/2).  302:- lib(os_sel/3).  303:- lib(os_sel/4).  304:- lib(os_mv/2).  305:- lib(os_cp/2).  306:- lib(os_ln_s/2).  307:- lib(os_type_base/2).  308
  309:- lib(stoics_lib:at_con/3).  310:- lib(stoics_lib:holds/2).  311:- lib(stoics_lib:compound/3).  312
  313:- lib(end(os_lib)).
 os_lib_version(-Version, -Date)
Current version and release date for the pack. 
?- os_version( V, D ).
V = 2:0:0,
D = date(2025,12,7)

*/

  326os_lib_version(2:0:0, date(2025,12,7)).
 os_version(-Version, -Date)
Synonym to os_lib_version/2 (the latter being the canonical predicate).

This was the original version predicate as the pack was originally named "os".

*/

  335os_version( V, D ) :-
  336     os_lib_version( V, D )