1/* Part of SWI-Prolog 2 3 Author: Jan Wielemaker 4 E-mail: J.Wielemaker@vu.nl 5 WWW: http://www.swi-prolog.org 6 Copyright (c) 2015, VU University Amsterdam 7 All rights reserved. 8 9 Redistribution and use in source and binary forms, with or without 10 modification, are permitted provided that the following conditions 11 are met: 12 13 1. Redistributions of source code must retain the above copyright 14 notice, this list of conditions and the following disclaimer. 15 16 2. Redistributions in binary form must reproduce the above copyright 17 notice, this list of conditions and the following disclaimer in 18 the documentation and/or other materials provided with the 19 distribution. 20 21 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 24 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 25 COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 26 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 27 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 28 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 29 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 31 ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 32 POSSIBILITY OF SUCH DAMAGE. 33*/ 34 35:- module(iostream, 36 [ open_any/5, % +Spec, +Mode, -Stream, -Close, +Options 37 close_any/1 % +Close 38 ]). 39:- use_module(library(option)). 40:- use_module(library(error)). 41:- if(exists_source(library(uri))). 42:- use_module(library(uri)). 43:- endif.
73:- multifile 74 open_hook/6. % +Spec, +Mode, -Stream, -Close, +Options0, -Options
Without loaded plugins, the open_any/5 processes the following
values for Specification. If no rule matches, open_any/5
processes Specification as file(Specification).
library(uri) to
be installed.The typical usage scenario is given in the code below, where <process> processes the input.
setup_call_cleanup(
open_any(Spec, read, In, Close, Options),
<process>(In),
Close).
Currently, the following libraries extend this predicate:
http and https schemes.121open_any(Spec, Mode, Stream, Close, Options) :- 122 \+ ( ground(Spec), % argument sanity check 123 var(Stream), 124 var(Close), 125 is_list(Options) ), 126 !, 127 open_error(Spec, Mode, Stream, Close, Options). 128open_any(Spec, _Mode, Stream, Close, Options) :- 129 is_stream(Spec), 130 !, 131 Stream = Spec, 132 input_options(Spec, Stream, true, Close, Options). 133:- if(current_predicate(uri_file_name/2)). 134open_any(Spec, Mode, Stream, Close, Options0) :- 135 atomic(Spec), 136 uri_file_name(Spec, File), 137 !, 138 open_any_builtin(file(File), Mode, Stream0, Close0, Options0, Options), 139 input_options(Stream0, Stream, Close0, Close, Options). 140:- endif. 141open_any(Spec, Mode, Stream, Close, Options0) :- 142 open_any_builtin(Spec, Mode, Stream0, Close0, Options0, Options), 143 !, 144 input_options(Stream0, Stream, Close0, Close, Options). 145open_any(Spec, Mode, Stream, Close, Options0) :- 146 open_hook(Spec, Mode, Stream0, Close0, Options0, Options), 147 !, 148 input_options(Stream0, Stream, Close0, Close, Options). 149open_any(Spec, Mode, Stream, Close, Options0) :- 150 open_any_builtin(file(Spec), Mode, Stream0, Close0, Options0, Options), 151 input_options(Stream0, Stream, Close0, Close, Options). 152 153open_error(Spec, _Mode, _Stream, _Close, _Options) :- 154 var(Spec), !, instantiation_error(Spec). 155open_error(_Spec, _Mode, Stream, _Close, _Options) :- 156 nonvar(Stream), 157 !, 158 uninstantiation_error(Stream). 159open_error(_Spec, _Mode, _Stream, Close, _Options) :- 160 nonvar(Close), 161 !, 162 uninstantiation_error(Close). 163open_error(_Spec, _Mode, _Stream, _Close, Options) :- 164 \+ is_list(Options), 165 !, 166 must_be(list, Options).
172input_options(Spec, Stream, Close0, Close, Options) :- 173 option(encoding(Enc), Options), 174 !, 175 Stream = Spec, 176 stream_property(Stream, encoding(Enc0)), 177 set_stream(Stream, encoding(Enc)), 178 mkconj(set_stream(Stream, encoding(Enc0)), Close0, Close). 179input_options(Stream, Stream, Close, Close, _). 180 181mkconj(set_stream(In,encoding(_)), close(In), close(In)) :- !. 182mkconj(true, X, X) :- !. 183mkconj(X, true, X) :- !. 184mkconj(X, Y, (X,Y)) :- !.
191open_any_builtin(stream(Stream), _Mode, Stream, true, Options, Options) :- 192 must_be(stream, Stream). 193open_any_builtin(file(Spec), Mode, Stream, close(Stream), Options0, Options) :- 194 ( compound(Spec) 195 -> absolute_file_name(Spec, Path, [access(Mode)|Options0]) 196 ; Path = Spec 197 ), 198 partition(open_option, Options0, OpenOptions, Options), 199 open(Path, Mode, Stream, OpenOptions). 200open_any_builtin(string(S), read, Stream, close(Stream), Options, Options) :- 201 open_string(S, Stream). 202 203open_option(encoding(_)). 204open_option(type(_)).
212close_any(Var) :- 213 var(Var), !, instantiation_error(Var). 214close_any((A,B)) :- close_any(A), close_any(B). 215close_any(true). 216close_any(close(Stream)) :- close(Stream). 217close_any(set_stream(S, encoding(Enc))) :- set_stream(S, encoding(Enc)). 218 219 220 /******************************* 221 * HOOKS * 222 *******************************/
Utilities to deal with streams
This library contains utilities that deal with streams, notably originating from non-built-in sources such as URLs, archives, windows, processes, etc.
The predicate open_any/5 acts as a broker between applications that can process data from a stream and libraries that can create streams from diverse sources. Without this predicate, processing data inevitally follows the pattern below. As call_some_open_variation can be anything, this blocks us from writing predicates such as
load_xml(From, DOM)that can operate on arbitrary input sources.setup_call_cleanup( call_some_open_variation(Spec, In), process(In), close(In)).Libraries that can open streams can install the hook iostream:open_hook/6 to make their functionality available through open_any/5.