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) 2003-2018, University of Amsterdam 7 VU University Amsterdam 8 CWI, Amsterdam 9 All rights reserved. 10 11 Redistribution and use in source and binary forms, with or without 12 modification, are permitted provided that the following conditions 13 are met: 14 15 1. Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 18 2. Redistributions in binary form must reproduce the above copyright 19 notice, this list of conditions and the following disclaimer in 20 the documentation and/or other materials provided with the 21 distribution. 22 23 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 24 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 25 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 26 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 27 COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 28 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 29 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 30 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 31 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 33 ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35*/ 36 37:- module(swi_option, 38 [ option/2, % +Term, +List 39 option/3, % +Term, +List, +Default 40 select_option/3, % +Term, +Options, -RestOpts 41 select_option/4, % +Term, +Options, -RestOpts, +Default 42 merge_options/3, % +New, +Old, -Merged 43 meta_options/3, % :IsMeta, :OptionsIn, -OptionsOut 44 dict_options/2 % ?Dict, ?Options 45 ]). 46:- autoload(library(lists), [selectchk/3]). 47:- autoload(library(error), [must_be/2, domain_error/2]). 48:- autoload(library(pairs), [map_list_to_pairs/3, pairs_values/2]). 49 50:- set_prolog_flag(generate_debug_info, false). 51 52:- meta_predicate 53 meta_options(, , ). 54 55/** <module> Option list processing 56 57The library(option) provides some utilities for processing option lists. 58Option lists are commonly used as an alternative for many arguments. 59Examples of built-in predicates are open/4 and write_term/3. Naming the 60arguments results in more readable code, and the list nature makes it 61easy to extend the list of options accepted by a predicate. Option lists 62come in two styles, both of which are handled by this library. 63 64 $ Name(Value) : 65 This is the preferred style. 66 67 $ Name = Value : 68 This is often used, but deprecated. 69 70Processing options inside time-critical code (loops) can cause serious 71overhead. One possibility is to define a record using library(record) 72and initialise this using make_<record>/2. In addition to providing good 73performance, this also provides type-checking and central declaration of 74defaults. 75 76 == 77 :- record atts(width:integer=100, shape:oneof([box,circle])=box). 78 79 process(Data, Options) :- 80 make_atts(Options, Attributes), 81 action(Data, Attributes). 82 83 action(Data, Attributes) :- 84 atts_shape(Attributes, Shape), 85 ... 86 == 87 88Options typically have exactly one argument. The library does support 89options with 0 or more than one argument with the following 90restrictions: 91 92 - The predicate option/3 and select_option/4, involving default are 93 meaningless. They perform an arg(1, Option, Default), causing 94 failure without arguments and filling only the first option-argument 95 otherwise. 96 - meta_options/3 can only qualify options with exactly one argument. 97 98@tbd We should consider putting many options in an assoc or record 99 with appropriate preprocessing to achieve better performance. 100@see library(record) 101@see Option processing capabilities may be declared using the 102 directive predicate_options/3. 103*/ 104 105%! option(?Option, +OptionList, +Default) is semidet. 106% 107% Get an Option from OptionList. OptionList can use the 108% Name=Value as well as the Name(Value) convention. 109% 110% @param Option Term of the form Name(?Value). 111 112option(Opt, Options, Default) :- 113 is_dict(Options), 114 !, 115 functor(Opt, Name, 1), 116 ( get_dict(Name, Options, Val) 117 -> true 118 ; Val = Default 119 ), 120 arg(1, Opt, Val). 121option(Opt, Options, Default) :- % make option processing stead-fast 122 functor(Opt, Name, Arity), 123 functor(GenOpt, Name, Arity), 124 ( get_option(GenOpt, Options) 125 -> Opt = GenOpt 126 ; arg(1, Opt, Default) 127 ). 128 129 130%! option(?Option, +OptionList) is semidet. 131% 132% Get an Option from OptionList. OptionList can use the Name=Value 133% as well as the Name(Value) convention. Fails silently if the 134% option does not appear in OptionList. 135% 136% @arg Option Term of the form Name(?Value). 137 138option(Opt, Options), is_dict(Options) => 139 functor(Opt, Name, 1), 140 get_dict(Name, Options, Val), 141 arg(1, Opt, Val). 142option(Opt, Options), is_list(Options) => 143 functor(Opt, Name, Arity), 144 functor(GenOpt, Name, Arity), 145 get_option(GenOpt, Options), 146 !, 147 Opt = GenOpt. 148 149get_option(Opt, Options) :- 150 memberchk(Opt, Options), 151 !. 152get_option(Opt, Options) :- 153 functor(Opt, OptName, 1), 154 arg(1, Opt, OptVal), 155 memberchk(OptName=OptVal, Options), 156 !. 157 158 159%! select_option(?Option, +Options, -RestOptions) is semidet. 160% 161% Get and remove Option from an option list. As option/2, removing 162% the matching option from Options and unifying the remaining 163% options with RestOptions. 164 165select_option(Opt, Options0, Options) :- 166 is_dict(Options0), 167 !, 168 functor(Opt, Name, 1), 169 get_dict(Name, Options0, Val), 170 arg(1, Opt, Val), 171 del_dict(Name, Options0, Val, Options). 172select_option(Opt, Options0, Options) :- % stead-fast 173 functor(Opt, Name, Arity), 174 functor(GenOpt, Name, Arity), 175 get_option(GenOpt, Options0, Options), 176 Opt = GenOpt. 177 178get_option(Opt, Options0, Options) :- 179 selectchk(Opt, Options0, Options), 180 !. 181get_option(Opt, Options0, Options) :- 182 functor(Opt, OptName, 1), 183 arg(1, Opt, OptVal), 184 selectchk(OptName=OptVal, Options0, Options). 185 186%! select_option(?Option, +Options, -RestOptions, +Default) is det. 187% 188% Get and remove Option with default value. As select_option/3, 189% but if Option is not in Options, its value is unified with 190% Default and RestOptions with Options. 191 192select_option(Option, Options, RestOptions, Default) :- 193 is_dict(Options), 194 !, 195 functor(Option, Name, 1), 196 ( del_dict(Name, Options, Val, RestOptions) 197 -> true 198 ; Val = Default, 199 RestOptions = Options 200 ), 201 arg(1, Option, Val). 202select_option(Option, Options, RestOptions, Default) :- 203 functor(Option, Name, Arity), 204 functor(GenOpt, Name, Arity), 205 ( get_option(GenOpt, Options, RestOptions) 206 -> Option = GenOpt 207 ; RestOptions = Options, 208 arg(1, Option, Default) 209 ). 210 211 212%! merge_options(+New, +Old, -Merged) is det. 213% 214% Merge two option lists. Merged is a sorted list of options using 215% the canonical format Name(Value) holding all options from New 216% and Old, after removing conflicting options from Old. 217% 218% Multi-values options (e.g., proxy(Host, Port)) are allowed, 219% where both option-name and arity define the identity of the 220% option. 221 222merge_options([], Old, Merged) :- 223 !, 224 canonicalise_options(Old, Merged). 225merge_options(New, [], Merged) :- 226 !, 227 canonicalise_options(New, Merged). 228merge_options(New, Old, Merged) :- 229 canonicalise_options(New, NCanonical), 230 canonicalise_options(Old, OCanonical), 231 sort(NCanonical, NSorted), 232 sort(OCanonical, OSorted), 233 ord_merge(NSorted, OSorted, Merged). 234 235ord_merge([], L, L) :- !. 236ord_merge(L, [], L) :- !. 237ord_merge([NO|TN], [OO|TO], Merged) :- 238 sort_key(NO, NKey), 239 sort_key(OO, OKey), 240 compare(Diff, NKey, OKey), 241 ord_merge(Diff, NO, NKey, OO, OKey, TN, TO, Merged). 242 243ord_merge(=, NO, _, _, _, TN, TO, [NO|T]) :- 244 ord_merge(TN, TO, T). 245ord_merge(<, NO, _, OO, OKey, TN, TO, [NO|T]) :- 246 ( TN = [H|TN2] 247 -> sort_key(H, NKey), 248 compare(Diff, NKey, OKey), 249 ord_merge(Diff, H, NKey, OO, OKey, TN2, TO, T) 250 ; T = [OO|TO] 251 ). 252ord_merge(>, NO, NKey, OO, _, TN, TO, [OO|T]) :- 253 ( TO = [H|TO2] 254 -> sort_key(H, OKey), 255 compare(Diff, NKey, OKey), 256 ord_merge(Diff, NO, NKey, H, OKey, TN, TO2, T) 257 ; T = [NO|TN] 258 ). 259 260sort_key(Option, Name-Arity) :- 261 functor(Option, Name, Arity). 262 263%! canonicalise_options(+OptionsIn, -OptionsOut) is det. 264% 265% Rewrite option list from possible Name=Value to Name(Value) 266 267canonicalise_options(Dict, Out) :- 268 is_dict(Dict), 269 !, 270 dict_pairs(Dict, _, Pairs), 271 canonicalise_options2(Pairs, Out). 272canonicalise_options(In, Out) :- 273 memberchk(_=_, In), % speedup a bit if already ok. 274 !, 275 canonicalise_options2(In, Out). 276canonicalise_options(Options, Options). 277 278canonicalise_options2([], []). 279canonicalise_options2([H0|T0], [H|T]) :- 280 canonicalise_option(H0, H), 281 canonicalise_options2(T0, T). 282 283canonicalise_option(Name=Value, H) :- 284 !, 285 H =.. [Name,Value]. 286canonicalise_option(Name-Value, H) :- 287 !, 288 H =.. [Name,Value]. 289canonicalise_option(H, H). 290 291 292%! meta_options(+IsMeta, :Options0, -Options) is det. 293% 294% Perform meta-expansion on options that are module-sensitive. 295% Whether an option name is module-sensitive is determined by 296% calling call(IsMeta, Name). Here is an example: 297% 298% == 299% meta_options(is_meta, OptionsIn, Options), 300% ... 301% 302% is_meta(callback). 303% == 304% 305% Meta-options must have exactly one argument. This argument will 306% be qualified. 307% 308% @tbd Should be integrated with declarations from 309% predicate_options/3. 310 311meta_options(IsMeta, Context:Options0, Options) :- 312 is_dict(Options0), 313 !, 314 dict_pairs(Options0, Class, Pairs0), 315 meta_options(Pairs0, IsMeta, Context, Pairs), 316 dict_pairs(Options, Class, Pairs). 317meta_options(IsMeta, Context:Options0, Options) :- 318 must_be(list, Options0), 319 meta_options(Options0, IsMeta, Context, Options). 320 321meta_options([], _, _, []). 322meta_options([H0|T0], IM, Context, [H|T]) :- 323 meta_option(H0, IM, Context, H), 324 meta_options(T0, IM, Context, T). 325 326meta_option(Name=V0, IM, Context, Name=(M:V)) :- 327 call(IM, Name), 328 !, 329 strip_module(Context:V0, M, V). 330meta_option(Name-V0, IM, Context, Name-(M:V)) :- 331 call(IM, Name), 332 !, 333 strip_module(Context:V0, M, V). 334meta_option(O0, IM, Context, O) :- 335 compound(O0), 336 O0 =.. [Name,V0], 337 call(IM, Name), 338 !, 339 strip_module(Context:V0, M, V), 340 O =.. [Name,M:V]. 341meta_option(O, _, _, O). 342 343%! dict_options(?Dict, ?Options) is det. 344% 345% Convert between an option list and a dictionary. One of the 346% arguments must be instantiated. If the option list is created, 347% it is created in canonical form, i.e., using Option(Value) with 348% the Options sorted in the standard order of terms. Note that the 349% conversion is not always possible due to different constraints 350% and conversion may thus lead to (type) errors. 351% 352% - Dict keys can be integers. This is not allowed in canonical 353% option lists. 354% - Options can hold multiple options with the same key. This is 355% not allowed in dicts. This predicate removes all but the 356% first option on the same key. 357% - Options can have more than one value (name(V1,V2)). This is 358% not allowed in dicts. 359% 360% Also note that most system predicates and predicates using this 361% library for processing the option argument can both work with 362% classical Prolog options and dicts objects. 363 364dict_options(Dict, Options) :- 365 nonvar(Dict), 366 !, 367 dict_pairs(Dict, _, Pairs), 368 canonicalise_options2(Pairs, Options). 369dict_options(Dict, Options) :- 370 canonicalise_options(Options, Options1), 371 map_list_to_pairs(key_name, Options1, Keyed), 372 sort(1, @<, Keyed, UniqueKeyed), 373 pairs_values(UniqueKeyed, Unique), 374 dict_create(Dict, _, Unique). 375 376key_name(Opt, Key) :- 377 functor(Opt, Key, 1), 378 !. 379key_name(Opt, _) :- 380 domain_error(option, Opt)