1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): 20% 21% END LICENSE BLOCK 22 23:- comment(alias, "Obsolete"). 24:- comment(summary, "Obsolete built-ins which should not be used in new code"). 25:- comment(categories, ["Built-In Predicates","Compatibility"]). 26 27:- tool(abolish_op / 2). 28:- tool(call_explicit / 2). 29:- tool(event_create / 2). 30:- tool(global_op / 3). 31:- tool((global) / 1). 32:- tool(make_array / 1). 33:- tool(make_array / 2). 34:- tool(make_local_array / 1). 35:- tool(make_local_array / 2). 36:- tool(erase_macro / 1). 37:- tool(local_record / 1). 38:- tool(abolish_record / 1). 39:- tool(is_built_in / 1). 40:- tool(set_error_handler / 2). 41:- tool(current_struct / 1). 42:- tool(portray_goal / 2). 43:- tool(tool / 1). 44:- tool(retract_all / 1). 45 46:- comment(lib / 2, [ 47 summary:"The library LibraryName is loaded into the module ModuleName if not loaded 48already. 49 50", 51 amode:(lib(++,+) is det), 52 desc:html(" 53 lib(Lib, Mod) is identical to use_module(library(Lib))@Mod. 54"), 55 args:["LibraryName" : "String or Atom.", "ModuleName" : "Atom."], 56 exceptions:[4 : "LibraryName is not instantiated.", 5 : "LibraryName is neither a string nor an atom.", 173 : "The library file LibraryName cannot be found."], 57 see_also:[ensure_loaded / 1, lib / 1, use_module / 1, (@)/2]]). 58 59:- comment(nodbgcomp / 0, [ 60 summary:"Tells the compiler to generate code without debug instructions and not to 61retain the source variable names. 62 63", 64 amode:(nodbgcomp is det), 65 desc:html(" Only predicates that have been compiled with debug instructions can 66 be traced by the debugger. The generation of debug instruction is 67 switched on by default, and can be switched off globally using 68 nodbgcomp/0 or set_flag(debug_compile, off). This can be reversed 69 using dbgcomp/0 or set_flag(debug_compile, on). This global 70 setting can always be overruled on a file-by-file basis using 71 pragma(debug) and pragma(nodebug) respectively. 72 73<P> 74 Internals of predicates that have been compiled without debug 75 instructions cannot be traced by the debugger (only entering and 76 leaving such a predicate can be shown). On the other hand, this 77 code uses less space and runs slightly faster than code with debug 78 instructions. So it makes sense to compile well-tested predicates 79 without debug instructions. Note however that predicates with 80 debug instructions that are called by predicates without debug 81 instructions are also invisible to the debugger. 82 83<P> 84 Calling nodbgcomp/0 is equivalent to set_flag(debug_compile, off), 85 set_flag(variable_names, off). 86 87<P> 88"), 89 eg:" 90Success: 91 [eclipse]: nodbgcomp, [user], dbgcomp, [user]. 92 q :- writeln(hi). 93 user compiled 36 bytes in 0.00 seconds 94 p :- q. 95 user compiled 32 bytes in 0.00 seconds 96 yes. 97 [eclipse]: trace. 98 Debugger switched on - creep mode 99 yes. 100 [eclipse]: p. 101 (1) 0 CALL p (dbg)?- creep 102 N (2) 1 CALL q (dbg)?- creep 103 hi 104 N (2) 1 EXIT q (dbg)?- creep % call to writeln/1 105 (1) 0 EXIT p (dbg)?- creep % invisible to the 106 yes. % debugger. 107 108 109 110", 111 see_also:[pragma/1, dbgcomp / 0, get_flag / 2, set_flag / 2, pragma / 1]]). 112 113:- comment(dbgcomp / 0, [ 114 summary:"Tells the compiler to generate code with debug instructions. Equivalent to 115the call to set_flag(debug_compile, on). 116 117", 118 amode:(dbgcomp is det), 119 desc:html(" Only predicates that have been compiled with debug instructions can be 120 traced by the debugger. 121 122<P> 123 The generation of debug instruction is switched on by default, and is 124 only switched off using nodbgcomp/0 or else using 125 set_flag(debug_compile, off). This can be reversed using dbgcomp/0 or 126 else using 127 set_flag(debug_compile, on). 128 129<P> 130 Predicates that have been compiled without debug instructions cannot be 131 traced by the debugger (only entering and leaving such a predicate can 132 be shown). 133 134<P> 135 On the other hand, this code uses less space and runs slightly faster 136 than code with debug instructions. So it makes sense to compile 137 well-tested predicates without debug instructions. 138 139<P> 140 Note however that predicates with debug instructions that are called by 141 predicates without debug instructions are invisible to the debugger. 142 143<P> 144"), 145 eg:" 146Success: 147 [eclipse]: dbgcomp, [user]. 148 p :- writeln(hello). 149 user compiled 60 bytes in 0.02 seconds. 150 [eclipse]: nodbgcomp, [user]. 151 q :- writeln(hello). 152 % generated code is smaller 153 user compiled 44 bytes in 0.00 seconds. 154 [eclipse]: trace. 155 yes. 156 Debugger switched on - creep mode 157 [eclipse]: p. 158 (1) 0 CALL p (dbg)?- creep 159 B (2) 1 CALL writeln(hello) (dbg)?- creep 160 hello 161 B (2) 1 EXIT writeln(hello) (dbg)?- creep 162 (1) 0 EXIT p (dbg)?- creep 163 yes. 164 [eclipse]: q. 165 N (1) 0 CALL q (dbg)?- creep % the inside of q/0 166 hello % is invisible 167 N (1) 0 EXIT q (dbg)?- creep % to the debugger 168 yes. 169 170 171 172 173", 174 see_also:[pragma/1, nodbgcomp / 0, get_flag / 2, set_flag / 2]]). 175 176:- comment(name / 2, [ 177 summary:"Succeeds if List is the corresponding list of ASCII codes for the atom or 178number Atomnumber. 179 180", 181 amode:(name(+,-) is det), 182 amode:(name(-,+) is det), 183 desc:html(" If Atomnumber is an atom or a number, unifies List with the list of its 184 corresponding ASCII codes. Real numbers can be any length in decimal 185 format, though fractions are evaluated to 6 decimal places. The codes 186 are of each character of the atom, or of each digit (or decimal point) 187 of the number. 188 189<P> 190 If List is instantiated, unifies Atomnumber with the atom or number 191 corresponding to this list of ASCII integers. 192 193<P> 194"), 195 args:["Atomnumber" : "Atom, number or variable.", "List" : "List of integers (each in the range 1 to 127) and/or variables, or else a variable."], 196 exceptions:[4 : "Neither Atomnumber nor List are ground.", 5 : "Atomnumber is instantiated, but not to an atom or a number.", 5 : "List is instantiated, but not to a list.", 6 : "List is a list containing an integer outside the range 1 to 127."], 197 eg:" 198 Success: 199 name(atom,[97,116,111,109]). 200 name(atom,[X,116|T]). (gives X=97,T=[111,109]). 201 name(/,[47]). 202 name(10,[49,48]). 203 name(20.0,[50,48,46,48]). 204 name(2,[50]). 205 name(+2,L). (gives L=[50]). 206 name(-2,L). (gives L=[45,50]). 207 name('1',[0'1]). 208 X is 1/3, name(X,Y). % X unifies with 0.333333 209 (gives Y=[48,46,51,51,51,51,51,51]). 210 Fail: 211 name(atom,[98,116,111,109]). 212 name('1',B), name(C,B), C='1'. % 1 does not unify with '1'. 213 name(1.0,[0'1,0'.,0'0,0'0]). % 1.0 is not 1.00 214 Error: 215 name(AN,[1,M]). (Error 4). 216 name(AN,L). (Error 4). 217 name(f(1,2),L). (Error 5). 218 name(AN,[128]). (Error 6). 219 name(AN,[0]). (Error 6). 220 221 222 223", 224 see_also:[number_string/2, atom_string / 2, char_int / 2, integer_atom / 2, string_list / 2, string_list/3, term_string / 2]]). 225 226:- comment(suspension_to_goal / 3, [ 227 summary:"Succeeds for an unwoken suspension and returns the corresponding Goal 228structure and caller module. 229 230", 231 amode:(suspension_to_goal(+,-,-) is semidet), 232 desc:html(" This built-in is used to access the contents of the abstract suspension 233 data type. It is complementary to make_suspension/2 as it returns the 234 original goal structure and the module where make_suspension/2 was 235 executed. If applied to an already woken suspension it fails. 236 237<P> 238 Note that a suspension is not a standard Prolog data structure and can 239 only be manipulated in a restricted way. In particular, a suspension is 240 not a term with functor 'GOAL' or 'WOKEN GOAL' although it is printed 241 this way by default. suspension_to_goal/3 is the only way to access the 242 contents of a suspension. 243 244<P> 245"), 246 args:["Susp" : "A suspension.", "Goal" : "A variable or a callable term.", "Module" : "A variable or a module."], 247 fail_if:"Fails if the suspension is already dead", 248 exceptions:[4 : "Susp is not instantiated.", 5 : "Susp is not a suspension.", 5 : "Goal is neither variable nor a callable term.", 5 : "Module is neither variable nor atom."], 249 eg:" 250[eclipse 1]: make_suspension(writeln(hello),S), 251 suspension_to_goal(S, Goal, Module). 252S = 'GOAL'(writeln(hello), eclipse) 253Goal = writeln(hello) 254Module = eclipse 255Delayed goals: 256 writeln(hello) 257yes. 258[eclipse 2]: make_suspension(writeln(hello),S), 259 call_suspension(S), 260 suspension_to_goal(S, Goal, Module). 261hello 262 263no (more) solution. 264 265 266", 267 see_also:[get_suspension_data/3, delayed_goals / 1, kill_suspension / 1, make_suspension / 3]]). 268 269:- comment(define_macro / 3, [ 270 summary:"Defines a macro transformation for the functor or type specified by 271TermClass. The transformation predicate is TransPred and Options is a list 272of options. 273 274", 275 amode:(define_macro(++,++,++) is det), 276 desc:html(" This predicate is used to define a macro transformation on a class of 277 terms. Macro transformation can be performed in two different 278 situations, when a term is read by one of the read predicates (read 279 macros) and when a term is written by one of the write predicates (write 280 macros). 281 282<P> 283 The TermClass specifies to which terms the transformation will be 284 applied: 285 286<P> 287Name/Arity transform all terms with the specified functor 288 289<P> 290type(Type) transform all terms of the specified type, where Type is one of 291 compound, string, integer, rational, float, breal, goal, atom, meta. 292 293<P> 294 The +TransPred argument specifies the predicate that will perform the 295 transformation. TransPred must be of arity 2 or 3 and be in the form: 296 trans_function(OldTerm, NewTerm [, Module]):- ... . 297 298<P> 299 At transformation time, the system will call TransPred in the module 300 where define_macro/3 was invoked. The term to transform is passed as 301 the first argument, the second is a free variable which should be bound 302 to the transformed term, and the optional third argument is the module 303 where the term is read or written. 304 305<P> 306 Options is a list which may be empty (in this case the macro defaults to 307 a local read term macro) or contain specifications from the following 308 categories: 309 310<P> 311 * visibility 312 313<P> 314 local: The transformation is only visible in this module (default). 315 316<P> 317 global: The transformation is globally visible. 318 319<P> 320 * mode 321 322<P> 323 read: This is a read macro and shall be applied after reading a term 324 (default). 325 326<P> 327 write: This is a write macro and shall be applied before printing a term. 328 329<P> 330 * type 331 332<P> 333 term: Transform all terms (default). 334 335<P> 336 clause: Transform only if the term is a program clause, i.e. inside 337 compile/1, assert/1 etc. Write macros are applied using the 'C' 338 option in the printf/2 predicate. 339 340<P> 341 goal: Write macros are applied when using the 'G' option in the 342 \tprintf/2 predicate. Note that goal (read) macros are obsolete, 343\tplease use inline/2 instead. 344 345<P> 346 * additional specification 347 348<P> 349 protect_arg: Disable transformation of subterms (optional). 350 351<P> 352 top_only: Consider only the whole term, not subterms (optional). 353 354<P> 355 A TermClass can have a read and a write macro attached at the same time. 356 By default, macro transformations are local to the module where they 357 were defined. That means, only read/write built-ins that are called 358 from inside this module do these transformations. Local macros hide 359 global ones. 360 361<P> 362"), 363 args:["TermClass" : "Term in the form Atom, Atom/Integer or type(Type).", "TransPred" : "Term in the form Atom/Integer.", "Options" : "Possibly empty list of option flags."], 364 exceptions:[4 : "One or more arguments not instantiated.", 5 : "TermClass not of form Atom, Atom/Integer or type(Type).", 5 : "TransPred not of form Atom/Integer.", 5 : "Options not a list or contains invalid flags.", 6 : "Arity of TransPred is not 2 or 3.", 6 : "Illegal flag in Options.", 161 : "Transformation already defined in the current module for TermClass"], 365 eg:" 366Success: 367 % The following example illustrates how a/1 may be 368 % transformed into b/2 using the reader. 369 [eclipse]: [user]. 370 trans_a(a(X),b(X,10)). 371 :-define_macro(a/1,trans_a/2,[]). 372 373 yes. 374 [eclipse]: read(X). 375 > a(fred). 376 377 X = b(fred, 10) 378 yes. 379 380 % 381 % Example showing use of protect_arg 382 % 383 [eclipse]: [user]. 384 ?- define_macro(b/1, trb/2, []), 385 define_macro(b_protect/1, trb/2, [protect_arg]), 386 define_macro(d/0, trd/2, []). 387 trb(X, newfunctor(Arg)) :- arg(1, X, Arg). 388 trd(d, newd). 389 390 yes. 391 [eclipse]: read(X1),read(X2). 392 > b(d). 393 > b_protect(d). 394 395 X1 = newfunctor(newd) % d is transformed 396 X2 = newfunctor(d) % d is not transformed 397 yes. 398 399 % 400 % Example showing use of type macros 401 % 402 [eclipse 1]: [user]. 403 tr_int(0, 0). 404 tr_int(N, s(S)) :- N > 0, N1 is N-1, tr_int(N1, S). 405 :- define_macro(type(integer), tr_int/2, []). 406 407 yes. 408 [eclipse 2]: read(X). 409 3. 410 411 X = s(s(s(0))) 412 yes. 413 414 % 415 % Example showing use of write macros 416 % 417 [eclipse 1]: [user]. 418 tr_s(0, 0). 419 tr_s(s(S), N) :- tr_s(S, N1), N is N1+1. 420 :- define_macro(s/1, tr_s/2, [write]). 421 422 yes. 423 [eclipse 2]: write(s(s(s(0)))). 424 3 425 yes. 426 427 428Error: 429 define_macro(X, trx/2, []). (Error 4). 430 define_macro(a/1, tra/2, [c]). (Error 6). 431 432 433 434", 435 see_also:[macro/3, portray/3, current_macro / 4, erase_macro / 1, phrase / 2, phrase / 3, inline / 2]]). 436 437:- comment(abolish_record / 1, [ 438 summary:"Remove the local record Key and all its recorded values. 439 440", 441 amode:(abolish_record(++) is det), 442 desc:html(" Remove the local record Key visible from the caller module and all its 443 recorded values. If global records are recorded under the key Key, they 444 become visible to that module. 445 446<P> 447 Key is equal to Key/0. 448 449<P> 450 If there is no local key declared in the caller module (with 451 local record/1), error 45 is raised. 452 453<P> 454 Note that abolish_record/1 is used to remove a records completely (even 455 its local declaration) so that a global record (if any) becomes visible 456 whereas erase_all/1 does not remove the local declaration. 457 458<P> 459"), 460 args:["Key" : "Key specification of the form Name/Arity or just Name."], 461 exceptions:[4 : "Key is not instantiated.", 5 : "Key is not of the form Atom or Atom/Integer.", 45 : "No local key Key is declared in the caller module."], 462 eg:" 463Success: 464 [eclipse]: record(type, integer). % global by default 465 yes. 466 [eclipse]: module(beer). 467 [beer]: record(type, string). % added global 468 yes. 469 [beer]: local record(type). % define a local 470 yes. 471 [beer]: record(type, lager), 472 record(type, stout). 473 yes. 474 [beer]: recorded(type, X). 475 X = lager More? (;) 476 X = stout More? (;) 477 no (more) solution. 478 [beer]: abolish_record(type/0). 479 yes. % the visible is now the global one again 480 [beer]: recorded(type, X). 481 X = integer More? (;) 482 X = string More? (;) 483 no (more) solution. 484 485Error: 486 abolish_record(X). (Error 4). 487 abolish_record(123). (Error 5). 488 local(record(key/3)), 489 abolish_record(key/3), 490 abolish_record(key/3). (Error 45). 491 492 493 494 495", 496 see_also:[erase / 2, erase_all / 1, record / 1, record / 2, recorded / 2, recorded / 3]]). 497 498:- comment(local_record / 1, [ 499 summary:"Declare the record with key Key to be local to the caller module 500 501", 502 amode:(local_record(++) is det), 503 desc:html(" Declare the record with key Key to be local to the caller module. 504 505<P> 506 Key is equal to Key/0. 507 508<P> 509"), 510 args:["Key" : "Key specification of the form Name/Arity or just Name."], 511 exceptions:[4 : "Key is not instantiated.", 5 : "Key is not of the form Atom or Atom/Integer.", 44 : "Key is already the key of a local record."], 512 eg:" 513Success: 514 [eclipse]: module(numbers). 515 [numbers]: local_record(type/0). 516 yes 517 [numbers]: record(type, integer), 518 record(type, real), 519 record(type, fractional). 520 yes. 521 [numbers]: module(beer). 522 [beer]: local_record(type), 523 record(type, lager), 524 record(type, stout). 525 yes. 526 [beer]: recorded(type, Type). 527 Type = lager More? (;) 528 Type = stout More? (;) 529 no (more) solution. 530 [beer]: module(numbers). 531 [numbers]: recorded(type, Type). 532 Type = integer More? (;) 533 Type = real More? (;) 534 Type = fractional More? (;) 535 no (more) solution. 536 [numbers]: module(other). 537 [other]: recorded(type, Type). 538 no (more) solution. 539 540Error: 541 local_record(X). (Error 4). 542 local_record(123). (Error 5). 543 local_record(key/3), 544 local_record(key/3). (Error 44). 545 546 547 548", 549 see_also:[record/1, abolish_record / 1, erase / 2, erase_all / 1, record / 2, recorded / 2]]). 550 551:- comment(make_array / 1, [ 552 summary:"Creates the untyped array or global variable Array. 553 554", 555 amode:(make_array(++) is det), 556 desc:html(" If Array is an Atom, a global variable (visible from all modules where a 557 local one of the same name is not defined) is created. Its value is 558 initialised to a free variable. 559 560<P> 561 If Array is a compound term, a global array of type prolog is created, 562 its dimension is the arity of the term Array and the size of each 563 dimension is specified by the corresponding argument of the term Array. 564 The elements of arrays of type prolog are initialised to free variables. 565 566<P> 567Note 568 make_array(A) is equivalent to make_array(A, prolog). 569 570<P> 571"), 572 args:["Array" : "Atom or ground compound term with integer arguments."], 573 exceptions:[4 : "Array is not ground.", 5 : "Array is not an atom or structure with integer arguments.", 6 : "The ground structure Array has arguments that are integers not greater than 0.", 42 : "An array with the same name and dimension as Array already exists."], 574 eg:" 575Success: 576 make_array(a(4)). 577 make_array(b(2,3)). 578 make_array(a(4)), make_array(a(4,1)). 579 make_array(a), make_array(a(1)). 580 581Error: 582 make_array(X). (Error 4). 583 make_array(a(6.0)). (Error 5). 584 make_array(a(0)). (Error 6). 585 make_array(a(-2)). (Error 6). 586 make_array(a(4)), make_array(a(5)). (Error 42). 587 588 589 590", 591 see_also:[array/1, current_array / 2, decval / 1, incval / 1, make_array / 2, make_local_array / 1, make_local_array / 2, getval / 2, setval / 2]]). 592 593 594:- comment(make_array / 2, [ 595 summary:"Creates the global array or global variable Array of type Type. 596 597", 598 amode:(make_array(++,+) is det), 599 desc:html(" If Array is an atom, a global variable only visible from the caller 600 module is created. The only type allowed for a global variable is 601 prolog or global_reference. However a typed gobal variable can be 602 create with make_local_array(a(1), Type) (accessed a a(0)). 603 604<P> 605 If Array is a compound term, a local array of type Type is created, its 606 dimension is the arity of the term Array and the size of each dimension 607 is specified by the corresponding argument of the term Array. The sizes 608 must be greater than 0, Type must not be global_reference. 609 610<P> 611 The elements of Prolog arrays are initialised depending on the type: 612 float, integer, byte and global_reference arrays are initialised with 0 613 values, prolog arrays are initialised with free variables. 614 615<P> 616 The valid elements indexes in the array range from 0 to the dimension 617 minus one. For example myarray created with make_array(myarray(3,4,5), 618 integer) contains 60 integers that may be accessed from myarray(0,0,0) 619 to myarray(2,3,4). 620 621<P> 622 Typed array use less space that untyped (i.e. prolog) ones. 623 624<P> 625 Global references access the original term with is variables, other 626 array types store a copy of the term. 627 628<P> 629"), 630 args:["Array" : "Atom or ground compound term with integer arguments.", "Type" : "Atom, one of float, integer, byte, prolog, global_reference."], 631 exceptions:[4 : "Either or both of the arguments are not ground.", 5 : "Array is not an atom or a compound term with integer arguments.", 5 : "Type is not an atom.", 6 : "The ground compound term Array has arguments that are integers not greater than 0.", 6 : "Type is not an atom in the above set.", 42 : "An array with the same name and dimension as Array already exists."], 632 eg:" 633Success: 634 make_array(a, prolog). 635 make_array(a(1), integer). 636 make_array(a(4), prolog). 637 make_array(b(2,3), float). 638 make_array(a(2), float), 639 make_array(a(3,2), byte). 640 641Error: 642 make_array(a(7), X). (Error 4). 643 make_array(a(6.0), float). (Error 5). 644 make_array(a(0), float). (Error 6). 645 make_array(a(2), atom). (Error 6). 646 make_array(a(4), float), 647 make_array(a(5), byte). (Error 42). 648 649 650 651", 652 see_also:[array/2, current_array / 2, getval / 2, make_array / 1, make_local_array / 1, make_local_array / 2, setval / 2]]). 653 654:- comment(make_local_array / 1, [ 655 summary:"Creates an array or global variable Array visible only in the caller 656module. 657 658", 659 amode:(make_local_array(++) is det), 660 desc:html(" If Array is an atom, a global variable only visible from the caller 661 module is created. Its value is initialised to a free variable. 662 663<P> 664 If Array is a compound term, a local array of type prolog is created, 665 its dimension is the arity of the term Array and the size of each 666 dimension is specified by the corresponding argument of the term Array. 667 The elements of arrays of type prolog are initialised to free variables. 668 669<P> 670Note 671 make_local_array(A) is equivalent to make_local_array(A, prolog). 672 673<P> 674"), 675 args:["Array" : "Atom or Ground compound term with integer arguments."], 676 exceptions:[4 : "Array is not ground.", 5 : "Array is not an atom or a structure with integer arguments.", 6 : "The ground structure Array has arguments that are integers not greater than 0.", 42 : "A local array with the same name and dimension as Array already exists."], 677 eg:" 678Success: 679 make_local_array(a). 680 make_local_array(a(1)). 681 make_local_array(a(4)). 682 make_local_array(b(2,3)). 683 make_local_array(a(4)), make_local_array(a(4,1)). 684 make_local_array(a), make_local_array(a(1)). 685 686Error: 687 make_local_array(X). (Error 4). 688 make_local_array(a(6.0)). (Error 5). 689 make_local_array(a(0)). (Error 6). 690 make_local_array(a(-2)). (Error 6). 691 make_local_array(a(4)), 692 make_local_array(a(5)). (Error 42). 693 694 695", 696 see_also:[array/1, current_array / 2, decval / 1, incval / 1, make_array / 1, make_array / 2, make_local_array / 2, getval / 2, setval / 2]]). 697 698:- comment(make_local_array / 2, [ 699 summary:"Creates an array or global variable Array of type Type visible only in the 700caller module. 701 702", 703 amode:(make_local_array(++,+) is det), 704 desc:html(" If Array is an atom, a global variable only visible from the caller 705 module is created. The only type allowed for a global variable is 706 prolog or global_reference. However a typed gobal variable can be 707 create with make_local_array(a(1), Type) (accessed a a(0)). 708 709<P> 710 If Array is a compound term, a local array of type Type is created, its 711 dimension is the arity of the term Array and the size of each dimension 712 is specified by the corresponding argument of the term Array. The sizes 713 must be greater than 0, Type must not be global_reference. 714 715<P> 716 The elements of Prolog arrays are initialised depending on the type: 717 float, integer, byte and global_reference arrays are initialised with 0 718 values, prolog arrays are initialised with free variables. 719 720<P> 721 The array indexes in the array range from 0 to the dimension minus one. 722 For example myarray create with make_local_array(myarray(3,4,5), 723 integer) contains 60 integers that may be accessed from myarray(0,0,0) 724 to myarray(2,3,4). 725 726<P> 727 Global references access the original term with is variables, other 728 array types store a copy of the term. 729 730<P> 731"), 732 args:["Array" : "Atom or ground compound term with integer arguments.", "Type" : "Atom, one of float, integer, byte, prolog, global_reference."], 733 exceptions:[4 : "Either or both of the arguments are not ground.", 5 : "Array is not an atom or a compound term with integer arguments.", 5 : "Type is not an atom.", 6 : "The ground compound term Array has arguments that are integers not greater than 0.", 6 : "Type is not an atom in the above set.", 42 : "An array with the same name and dimension as Array already exists."], 734 eg:" 735Success: 736 make_local_array(a, prolog). 737 make_local_array(a(1), integer). 738 make_local_array(a(4), prolog). 739 make_local_array(b(2,3), float). 740 make_local_array(a(2), float), 741 make_local_array(a(3,2), byte). 742 make_array(a(2,3), integer), 743 make_local_array(a(2,3), integer). 744 745Error: 746 make_local_array(a(7), X). (Error 4). 747 make_local_array(a(6.0), float). (Error 5). 748 make_local_array(a(0), float). (Error 6). 749 make_local_array(a(2), atom). (Error 6). 750 make_local_array(a(4), float), 751 make_local_array(a(5), byte). (Error 42). 752 753 754 755", 756 see_also:[array/2, current_array / 2, getval / 2, make_array / 1, make_array / 2, make_local_array / 1, setval / 2]]). 757 758:- comment(suffix / 2, [ 759 summary:"Succeeds if the string Suffix is the extension part of the input string 760FileName. 761 762", 763 amode:(suffix(+,-) is det), 764 desc:html(" Used to find the extension (i.e. suffix) Suffix of the input string 765 file name FileName. FileName is a string of a (relative or absolute) 766 file pathname. Suffix includes the leading ``.''. 767 768<P> 769"), 770 args:["FileName" : "String or atom.", "Suffix" : "String or variable."], 771 exceptions:[4 : "FileName is not instantiated.", 5 : "FileName is not a string or atom.", 5 : "Suffix is neither a string nor a variable."], 772 eg:" 773Success: 774 suffix(\"a.b\",\".b\"). 775 suffix(\"dead.letter\",\".letter\"). 776 suffix(\"top.pl\",S). (gives S=\".pl\"). 777 suffix(\"bugs\",S). (gives S=\"\"). 778 suffix(\"../my.pl\",S). (gives S=\".pl\"). 779 suffix(\"../user/my.c\",S). (gives S=\".c\"). 780 suffix(\"/home/user/pl/.trace\",S). (gives S=\".trace\"). 781 782Fail: 783 suffix(\"file.pl\",\".c\"). 784 785Error: 786 suffix(F,S). (Error 4). 787 suffix('file1.pl',S). (Error 5). 788 suffix(\"file1.pl\",'.pl'). (Error 5). 789 790 791 792", 793 see_also:[pathname / 4, pathname / 2]]). 794 795:- comment(pathname / 2, [ 796 summary:"Succeeds if the pathname FilePath, if stripped of its file name, gives 797Path, the path up to the parent directory of the file. 798 799", 800 amode:(pathname(+,-) is det), 801 desc:html(" Used to check if the pathname FilePath, when stripped of its file name, 802 unifies with Path, the path up to the parent directory of the file. 803 pathname(File, Path) is equal to pathname(File, Path, _). 804 805<P> 806"), 807 args:["FilePath" : "String or atom.", "Path" : "Variable or string."], 808 exceptions:[4 : "FilePath is not instantiated.", 5 : "FilePath is not a string or atom.", 5 : "Path is neither a string nor a variable."], 809 eg:" 810Success: 811 [eclipse]: pathname(\"/home/user/userfile\", P). 812 P = \"/home/user/\" 813 yes. 814 815 pathname(\"/home/user\",\"/home/\"). 816 pathname(\"/home/\",\"/home/\"). 817 pathname(\"/home\",\"/\"). 818 pathname(\"/\",\"/\"). 819 820Fail: 821 pathname(\"/home/\",\"/\"). 822 823Error: 824 pathname(F,P). (Error 4). 825 pathname('/home/user/',P). (Error 5). 826 827 828 829", 830 see_also:[pathname / 4, pathname / 3, suffix / 2]]). 831 832:- comment(set_prompt / 3, [ 833 summary:"The prompt Prompt is output on the stream OutStream for input to the input 834stream InStream. 835 836", 837 amode:(set_prompt(+,+,+) is det), 838 desc:html(" The prompt Prompt is output on the stream OutStream for input to the 839 input stream InStream. 840 841<P> 842 When new data is to be read from an input stream, the system prints on 843 the specified output stream a prompt, to notify the user for input. 844 845<P> 846 InStream and OutStream can be symbolic stream names (atom) or physical 847 stream numbers (integer). 848 849<P> 850 InStream must be an existing stream open in read or update mode. 851 OutStream must be an existing stream open in write or update mode. 852 853<P> 854 Note that the prompt for toplevel-input printed by the system at the end 855 of each query is made using the predicate toplevel-prompt/1 and not by 856 using the string set by set_prompt/3. 857 858<P> 859"), 860 args:["InStream" : "Integer (stream number) or Atom (reserved or user-defined symbolic stream name).", "Prompt" : "String or atom.", "OutStream" : "Integer (stream number) or Atom (reserved or user-defined symbolic stream name)."], 861 exceptions:[4 : "One or more of InStream, Prompt or OutStream are not instantiated.", 5 : "Either InStream or OutStream (or both) is neither an atom nor an integer.", 5 : "Prompt is neither an atom nor a string.", 192 : "InStream is in write mode.", 192 : "OutStream is in read mode."], 862 eg:" 863Success: 864 [eclipse]: get_prompt(input,_,Out), 865 > set_prompt(input,\"myprompt> \",Out). 866 Out = 1 867 yes. 868 [eclipse]: get_prompt(input,Prompt,_), 869 myprompt> !. 870 Prompt = \"myprompt> \" 871 yes. 872 873 [eclipse]: read( input,X). 874 > a. 875 X = a 876 yes. 877 [eclipse]: set_prompt(input, \"Enter a term: \", output). 878 yes. 879 [eclipse]: read(input,X). 880 Enter a term: a. 881 X = a 882 yes. 883 884 [eclipse]: get_stream(debug_input,S), 885 > set_prompt(S, \" DEBUG: \", 1). 886 S = 3 887 yes. 888 [eclipse]: trace. 889 yes. 890 [eclipse]: length([a,b],N). 891 S (1) 0 CALL length([a, b], _g52) DEBUG: creep 892 S (1) 0 EXIT length([a, b], 2) DEBUG: creep 893 N = 2 894 yes. 895 896 897Error: 898 set_prompt(4, Prompt, 1). (Error 4). 899 set_prompt(4, 4, 1). (Error 5). 900 set_prompt(output, \"p> \", Stream). (Error 192). 901 902 903 904", 905 see_also:[set_stream_property/3, get_prompt / 3]]). 906 907:- comment(current_stream / 3, [ 908 summary:"Succeeds if there is currently an open stream Stream open to the file Name 909in the mode Mode. This predicate is obsolete, use current_stream/1 and 910get_stream_info/3 instead. 911 912", 913 amode:(current_stream(-,-,-) is nondet), 914 amode:(current_stream(-,-,+) is semidet), 915 desc:html(" Unifies Name with the file name and Mode with the mode of the stream 916 Stream. If Stream is a variable, it is bound to all open streams on 917 backtracking. 918<P> 919 If the stream is not a file, the Name argument has different 920 meanings: If it is the user's console, the pseudo file names 921 'user' or 'error' are returned. If the stream is a string stream, 922 Name returns the current contents of the string stream. 923<P> 924 The following table illustrates the predefined symbolic system streams 925 with the name, mode, and initial physical stream number that they are 926 initially assigned to. 927<P> 928<PRE> 929 Logical Name Mode Number 930 input user read 0 931 stdin user read 0 932 output user write 1 933 stdout user write 1 934 warning_output user write 1 935 log_output user write 1 936 error error write 2 937 stderr error write 2 938 null null update 3 939</PRE> 940<P> 941 Also see set_stream/2 for details on how to assign a symbolic stream 942 name to a physical stream, or to redirect a symbolic stream name. 943 944<P> 945"), 946 args:["Name" : "Filename (atom or string), contents of string stream (string) or variable.", "Mode" : "One of the atoms read, write, update, string or a variable.", "Stream" : "Physical stream number (integer), or a variable."], 947 fail_if:"Fails if Stream is not a stream", 948 exceptions:[5 : "Name is instantiated, but not to an atom or a string.", 5 : "Mode is not an atom.", 5 : "Stream is instantiated, but not to an atom or an integer."], 949 eg:" 950Success: 951 current_stream(Name,Mode,Stream). % returns all 952 % open streams. 953 954 [eclipse]: current_stream(error,Mode,Stream). 955 Mode = write 956 Stream = 2 More? (;) 957 yes. 958 959 [eclipse]: open(file,update,s), current_stream(file,M,s). 960 M = update 961 yes. 962 963 [eclipse]: open(F,string(10),f), writeln(f, \"bigstring\"), 964 > current_stream(Data,M,f). 965 F = \"bigstring\\n\" 966 Data = \"bigstring\\n\" 967 M = string 968 yes. 969 970Fail: 971 open(file,update,f), current_stream(\"file\",M,f). 972 current_stream(X,no,Y). 973 974Error: 975 current_stream(12,Mode,String). (Error 5). 976 977 978 979", 980 see_also:[current_stream/1, open / 3, open / 4, get_stream_info / 3]]). 981 982:- comment(get_prompt / 3, [ 983 summary:"Succeeds if the prompt for the stream InStream is Prompt and is written to 984the stream OutStream. 985 986", 987 amode:(get_prompt(+,-,-) is det), 988 desc:html(" Used to get the prompt Prompt of the input stream InStream which is 989 output to the stream OutStream. 990 991<P> 992 When new data is to be read from an input stream, the system prints on 993 the specified output stream a prompt, to notify the user. 994 995<P> 996 InStream (and OutStream, when instantiated) can be a symbolic stream name 997 (atom) or a physical stream number (integer). InStream must be an 998 existing stream open in read or update mode. OutStream must be open in 999 write or update mode. 1000 1001<P> 1002 Note that the prompt for toplevel-input printed by the system at the end 1003 of each query is made using the predicate toplevel-prompt/1 and not by 1004 using the string set by set_prompt/3. 1005 1006<P> 1007"), 1008 args:["InStream" : "Integer (stream number) or Atom (reserved or user-defined symbolic stream name).", "Prompt" : "String, atom or variable.", "OutStream" : "Variable,Integer or Atom."], 1009 exceptions:[4 : "InStream is not instantiated.", 5 : "Either InStream or OutStream (or both) is instantiated, but is neither an atom nor an integer.", 5 : "Prompt is instantiated, but to neither an atom nor a string.", 192 : "InStream is not an input stream.", 192 : "OutStream is not an output stream.", 193 : "Either InStream or OutStream is an illegal stream specification (e.g. does not exist)."], 1010 eg:" 1011Success: 1012 [eclipse]: get_prompt(debug_input,_,input),% find where the 1013 % prompt is output; 1014 > set_prompt(debug_input,\"> \",input). % change it 1015 yes. % destructively. 1016 1017 [eclipse]: read(X). 1018 > a. 1019 X = a 1020 yes. 1021 [eclipse]: get_prompt(input, Old, Out), 1022 > set_prompt(input, \"Enter a term: \", Out), read(X). 1023 Enter a term: a. 1024 Old = \"> \" 1025 Out = 1 1026 X = a 1027 yes. 1028 1029 [eclipse]: get_stream(debug_input,S), % debug input prompt 1030 > set_prompt(S, \" DEBUG: \", 1). 1031 S = 3 1032 yes. 1033 [eclipse]: trace. 1034 yes. 1035 [eclipse]: atom_string(atom, String). 1036 B (1) 0 CALL atom_string(atom, _g52) DEBUG: creep 1037 B (1) 0 EXIT atom_string(atom, \"atom\") DEBUG: creep 1038 String = \"atom\" 1039 yes. 1040 1041Fail: 1042 get_prompt(0,\"\",S). 1043 1044Error: 1045 get_prompt(I, \"p\", Stream). (Error 4). 1046 get_prompt(0, Prompt, \"5\"). (Error 5). 1047 get_prompt(1, Prompt, 2). (Error 192). % 1 in write mode 1048 get_prompt(0, Prompt, 30). (Error 193). % no such stream 1049 1050 1051 1052", 1053 see_also:[set_prompt / 3, get_stream_info / 3]]). 1054 1055:- comment(abolish_op / 2, [ 1056 summary:"Remove the declaration of the visible operator +Name of associativity 1057Associativity. 1058 1059", 1060 amode:(abolish_op(+,+) is det), 1061 desc:html(" Used to remove the local declaration of the operator Name defined in the 1062 caller module or to remove the hiding of a global operator declaration 1063 (made with local_op(0, Associativity, Name)) so that the global operator 1064 declaration becomes visible again. 1065 1066<P> 1067 If no operator Name with associativity Associativity is visible from the 1068 caller module, error 72 is raised. 1069 1070<P> 1071 If Associativity is not one of following atoms, a range error is raised: 1072 1073<P> 1074<PRE> 1075---------------------------- 1076 xfx infix 1077 xfy infix 1078 yfx infix 1079 fx prefix 1080 fy prefix 1081 xf postfix 1082 yf postfix 1083</PRE> 1084"), 1085 args:["Name" : "Atom", "Associativity" : "Atom."], 1086 exceptions:[4 : "Name or Associativity is uninstantiated.", 5 : "Name is not an atom.", 5 : "Associativity is not an atom.", 6 : "Associativity is not a valid associativity name.", 72 : "there is no operator Name with associativity Associativity visible from the caller module."], 1087 eg:" 1088Success: 1089 [eclipse]: op(100, fx, -+-). 1090 yes. % defined a global prefix operator 1091 [eclipse]: local_op(0, fy, -+-). 1092 yes. % hide any global prefix operator 1093 [eclipse]: current_op(X, Y, -+-). 1094 no (more) solution. 1095 [eclipse]: abolish_op(-+-, fy). 1096 yes. % remove the hiding 1097 [eclipse]: current_op(X, Y, -+-). 1098 X = 100 1099 Y = fx More? (;) % global visible again 1100 no (more) solution. 1101 [eclipse]: abolish_op(-+-, fx). 1102 yes. % remove the global definition 1103 [eclipse]: current_op(X, Y, -+-). 1104 no (more) solution. 1105 1106Error: 1107 abolish_op(X, yfx). (Error 4) 1108 abolish_op(+, X). (Error 4) 1109 abolish_op(\"+\", yfx). (Error 5) 1110 abolish_op(+, 12). (Error 5) 1111 abolish_op(+, fff). (Error 6) 1112 abolish_op(no_op, fx). (Error 72) 1113 local_op(100, fx, +), 1114 abolish_op(+, fy). (Error 72). 1115 1116 1117 1118", 1119 see_also:[current_op / 3, global_op / 3, op / 3]]). 1120 1121:- comment(erase_macro / 1, [ 1122 summary:"Erases the macro definition for TransTerm done in the current module 1123 1124", 1125 amode:(erase_macro(+) is det), 1126 desc:html(" The macro (either global or local) defined for TransTerm in the current 1127 module is erased. If there was no macro definition, an error is raised. 1128 1129<P> 1130"), 1131 args:["TransTerm" : "Term in the form Atom/Integer."], 1132 exceptions:[4 : "TransTerm is not instantiated.", 5 : "TransTerm not of form Atom/Integer.", 162 : "No macro transformation defined in this module for TransTerm."], 1133 eg:" 1134 Success: 1135 erase_macro(a/1). (if a macro was defined for a/1) 1136 Error: 1137 erase_macro(X). (Error 4). 1138 erase_macro(a). (Error 5). 1139 erase_macro(a/1). (Error 162). % if no macro was defined. 1140 1141 1142 1143", 1144 see_also:[erase_macro/2, current_macro / 4, define_macro / 3, phrase / 2, phrase / 3]]). 1145 1146:- comment((global) / 1, [ 1147 summary:"Declares the procedure(s) and other modular items specified by SpecList 1148to be global. 1149", 1150 template:"global ++SpecList", 1151 amode:(global(++) is det), 1152 desc:html("\ 1153 This predicate is obsolete - global visibility is being deprecated. 1154 For procedures, use export declarations instead. For other global 1155 items, replace them by local ones and, if necessary, provide exported 1156 access procedures to manipulate them. 1157<P> 1158 This predicate was used to declare the visibility of procedures 1159 and other names as global. SpecList is a comma-separated list 1160 of expressions of the following form: 1161<DL> 1162<DT><STRONG> Name/Arity</STRONG><DD> 1163 procedure specification (since global procedures are no longer 1164 supported, this is now the same as exporting) 1165 1166<DT><STRONG> variable(Name)</STRONG><DD> 1167 non-logical variable declaration 1168 1169<DT><STRONG> reference(Name)</STRONG><DD> 1170 reference declaration 1171 1172<DT><STRONG> array(Name)</STRONG><DD> 1173 untyped non-logical array declaration 1174 1175<DT><STRONG> array(Name,Type)</STRONG><DD> 1176 typed non-logical array declaration 1177 1178<DT><STRONG> record(Name)</STRONG><DD> 1179 record key declaration 1180 1181<DT><STRONG> struct(Prototype)</STRONG><DD> 1182 structure declaration 1183 1184<DT><STRONG> op(Prec,Assoc,Name)</STRONG><DD> 1185 operator declaration 1186 1187<DT><STRONG>macro(Functor,Transformation,Options)</STRONG><DD> 1188 macro (input transformation) declaration 1189 1190<DT><STRONG>portray(Functor,Transformation,Options)</STRONG><DD> 1191 portray (output transformation) declaration 1192</DL> 1193 For backward compatibility, global declarations of variables, 1194 references, arrays, records, structures, operators and macros 1195 still work. However, global procedure declarations now have the 1196 same effect as an export declaration and generate a warning message. 1197"), 1198 args:["SpecList" : "Sequence of modular item specifications."], 1199 exceptions:[4 : "SpecList is not instantiated.", 1200 5 : "SpecList is instantiated, but not to a valid global specification", 1201 94 : "SpecList is already imported."], 1202 eg:" 1203Success: 1204 1205 [eclipse]: [user]. 1206 :- global p/1. 1207 p(eclipse). 1208 user compiled 40 bytes in 0.00 seconds 1209 yes. 1210 [eclipse]: module(m). 1211 [m]: [user]. 1212 :- local p/1. % can be omitted here since default is local. 1213 p(m). 1214 user compiled 40 bytes in 0.00 seconds 1215 yes. 1216 [m]: p(X). 1217 X = m 1218 yes. 1219 [m]: abolish(p/1). 1220 yes. % local predicate is abolished, global is visible again 1221 [m]: p(X). 1222 X = eclipse 1223 yes. 1224 1225Error: 1226 1227 global(Q). (Error 4). 1228 global(\"Pred\"). (Error 5). 1229 1230 [eclipse]: [user]. 1231 % :- tool(t/0) here would prevent error 62 in global(t/0) below 1232 p :- t. 1233 user compiled 32 bytes in 0.02 seconds 1234 yes. 1235 [eclipse]: module(m). 1236 [m]: [user]. 1237 :- tool(t/0, writeln/1). 1238 :- global(t/0). (Error 62). 1239 1240 global(p/0), global(p/0). (Error 89). (warning) 1241 (import p/0 from m), global(p/0). (Error 94). 1242 global(true/0). (Error 95). 1243 1244 1245 1246", 1247 see_also:[(export) / 1, (import) / 1, (local) / 1]]). 1248 1249:- comment(autoload / 2, [ 1250 summary:"Declares the predicates in ListOfPredSpec to be autoloading from the module 1251Library, which is in the file Library.pl in one of the library directories. 1252 1253", 1254 amode:(autoload(+,++) is det), 1255 desc:html(" Declares the predicates in the list ListOfPredSpec as defined in the 1256 file Library. If any of the specified predicates is called, the system 1257 looks in the library_path directories for the file Library.pl, compiles 1258 it using lib/2 and then re-calls the predicate. The file is supposed to 1259 contain a module_interface/1 or begin_module/1 directive at its 1260 beginning but it can be omitted and then Library is used as the module 1261 name. 1262 1263<P> 1264 Predicates declared as autoloaded are always defined as global but note 1265 that the module directive in a file erases the module completely so that 1266 the autoloaded procedure (and its visibility) are removed completely 1267 before being recompiled. This means that the global declaration must be 1268 present in the file. 1269 1270<P> 1271 The predicate autoload_tool/2 is the same except that all the predicates 1272 are declared to be tools, using tool/1. 1273 1274<P> 1275"), 1276 args:["Library" : "Atom.", "ListOfPredSpecList" : "of expressions of the form Atom/Integer."], 1277 exceptions:[4 : "Library or ListOfPredSpec is not instantiated.", 5 : "Library is instantiated, but not to an atom.", 5 : "ListOfPredSpec is instantiated, but not to list a of expressions of the form Atom/Integer.", 173 : "Library file Library.pl not found. (when calling an autoloaded predicate)"], 1278 eg:" 1279Success: 1280 [eclipse]: get_flag(library_path, Path), 1281 get_flag(cwd, Cwd), 1282 set_flag(library_path, [Cwd | Path]). 1283 Cwd = \"/home/user/\" 1284 Path = [\"/usr/local/ECLIPSE/lib\"] 1285 yes. 1286 [eclipse]: open(\"my_lib.pl\", write, s), 1287 write(s, \":- module(my_lib).\\n\"), 1288 write(s, \":- global p/0.\\n\"), 1289 write(s, \"p :- write(hello).\\n\"), 1290 close(s). 1291 yes. 1292 [eclipse]: autoload(my_lib, [p/0]). 1293 yes. 1294 [eclipse]: p. % when p/0 is called, the library is 1295 % compiled first, ie. autoloaded. 1296 loading the library /home/user/my_lib.pl 1297 hello 1298 yes. 1299 [eclipse]: p. % p/0 is not an autoloaded pred anymore 1300 hello 1301 yes. 1302 1303Error: 1304 autoload(Lib, [p/0]). (Error 4). 1305 autoload(a_lib, L). (Error 4). 1306 autoload(a_lib, [1]). (Error 5). 1307 autoload(a_lib, p/0). (Error 5). 1308 autoload(\"a_lib\", [p/0]). (Error 5). 1309 autoload(no_file, [p/0]). (Error 173). 1310 1311 1312 1313", 1314 see_also:[ensure_loaded/1, autoload_tool / 2, lib / 1, lib / 2, tool / 1]]). 1315 1316:- comment(autoload_tool / 2, [ 1317 summary:"Declares the predicates in ListOfPredSpec to be autoloading tools from the 1318module (file) Library.pl. 1319 1320", 1321 amode:(autoload_tool(+,++) is det), 1322 desc:html(" Declares the predicates in the list ListOfPredSpec as tools defined in 1323 the file Library. If any of the specified tools is called, the system 1324 looks in the library_path directories for the file Library.pl, compiles 1325 it using lib/1 and re-calls the tool. The file is supposed to contain 1326 a module_interface/1 or begin_module/1 directive at its beginning but it 1327 can be omitted and then Library is used as the module name. 1328 1329<P> 1330 The library file Library.pl must contain a tool/2 call for each of the 1331 specified predicates. 1332 1333<P> 1334 Predicates declared as autoloaded are always defined as global but note 1335 that the module directive in a file erase the module completely so that 1336 the autoloaded procedure (and its visibility) are removed completely 1337 before being recompiled. This means that the global declaration must be 1338 present in the file. 1339 1340<P> 1341"), 1342 args:["Library" : "Atom.", "ListOfPredSpecList" : "of expressions of the form Atom/Integer."], 1343 exceptions:[4 : "Library or ListOfPredSpec is not instantiated.", 5 : "Library is instantiated, but not to an atom.", 5 : "ListOfPredSpec is instantiated, but not to a list of expressions of the form Atom/Integer.", 62 : "a call to PredSpec has already been compiled before the tool declaration (``inconsistent procedure redefinition'').", 173 : "Library file Library.pl not found. (when calling an autoloaded predicate)"], 1344 eg:" 1345Success: 1346 [eclipse]: get_flag(library_path, Path), 1347 get_flag(cwd, Cwd), 1348 set_flag(library_path, [Cwd | Path]). 1349 Cwd = \"/home/user/\" 1350 Path = [\"/usr/local/ECLIPSE/lib\"] 1351 yes. 1352 [eclipse]: open(\"my_lib.pl\", write, s), 1353 write(s, \":- module(my_lib).\\n\"), 1354 write(s, \":- global p/0.\\n\"), 1355 write(s, \":- tool(p/0, writeln/1).\"), 1356 close(s). 1357 yes. 1358 [eclipse]: autoload_tool(my_lib, [p/0]). 1359 yes. 1360 [eclipse]: p. % when p/0 is called, the library is 1361 % compiled first, ie. autoloaded. 1362 loading the library /home/user/my_lib.pl 1363 eclipse 1364 yes. 1365 [eclipse]: p. % p/0 is not an autoloaded pred anymore 1366 eclipse 1367 yes. 1368 1369Error: 1370 autoload_tool(Lib, [p/0]). (Error 4). 1371 autoload_tool(a_lib, L). (Error 4). 1372 autoload_tool(\"a_lib\", [p/0]). (Error 5). 1373 autoload_tool(a_lib, [1]). (Error 5). 1374 autoload_tool(a_lib, p/0). (Error 5). 1375 1376 [eclipse]: [user]. 1377 p :- t. % call compiled before tool declaration 1378 user compiled 32 bytes in 0.00 seconds 1379 yes. 1380 [eclipse]: autoload_tool(a_lib, [t/0]). (Error 62). 1381 1382 autoload_tool(not_a_file, [p/0]). (Error 173). 1383 1384 1385 1386", 1387 see_also:[ensure_loaded/1, autoload / 2, lib / 1, lib / 2, tool / 1]]). 1388 1389:- comment(begin_module / 1, [ 1390 summary:"Start the definition of the body of the Module. 1391 1392", 1393 amode:(begin_module(+) is det), 1394 desc:html(" This is a directive that can occur only in a compiled file. Module must 1395 be an existing, non-locked module. All following code will be added to 1396 the module Module up to the next begin_module/1 or module_interface/1 1397 directive or up to the file end. 1398 1399<P> 1400"), 1401 args:["Module" : "Atom."], 1402 exceptions:[4 : "Module is not instantiated.", 5 : "Module is not an atom.", 68 : "When called from Prolog.", 80 : "Module is not a module.", 82 : "Module is locked."], 1403 eg:" 1404Success: 1405 [eclipse 2]: [user]. 1406 :- module_interface(m). 1407 :- op(700, xf, there). 1408 :- export p/1. 1409 :- begin_module(m). 1410 p(X) :- writeln(X). 1411 user compiled 56 bytes in 0.03 seconds 1412 yes. 1413 [eclipse 3]: p(hello there). 1414 syntax error: postfix/infix operator expected 1415 | p(hello there). 1416 | ^ here 1417 [eclipse 3]: use_module(m). 1418 1419 yes. 1420 [eclipse 4]: p(hello there). 1421 hello there 1422 1423 yes. 1424 1425Error: 1426 begin_module(M). (Error 4). 1427 begin_module(1). (Error 5). 1428 begin_module(a_locked_module). (Error 82). 1429 1430 1431 1432", 1433 see_also:[module/1, create_module / 1, erase_module / 1, current_module / 1, module_interface / 1]]). 1434 1435:- comment(module_interface / 1, [ 1436 summary:"Create the module Module and start defining its interface. 1437 1438", 1439 amode:(module_interface(+) is det), 1440 desc:html(" This is a directive that can occur only in a compiled file. If Module 1441 is an existing module, it is first erased. Then a new module is created 1442 and all following code up to the next begin_module/1 or 1443 module_interface/1 directive or the file end defines the interface part 1444 of this module. The module interface can contain both queries and 1445 predicate definitions, however usually only those predicates need to be 1446 defined in the interface that must be always compiled in order to read 1447 the module body. For instance, macro transformation predicates for 1448 macros used in the file must be compiled, otherwise the parser cannot 1449 parse the file. If another module uses this module by means of the 1450 use_module/1 predicate, all queries in the module interface except 1451 export/1 and global/1 will be executed in that module, and exported 1452 predicates will be imported into it. 1453 1454<P> 1455"), 1456 args:["Module" : "Atom."], 1457 exceptions:[4 : "Module is not instantiated.", 5 : "Module is not an atom.", 68 : "When called from Prolog.", 82 : "Module is locked."], 1458 eg:" 1459Success: 1460 [eclipse 2]: [user]. 1461 :- module_interface(m). 1462 :- op(700, xf, there). 1463 :- export p/1. 1464 :- begin_module(m). 1465 p(X) :- writeln(X). 1466 user compiled 56 bytes in 0.03 seconds 1467 yes. 1468 [eclipse 3]: p(hello there). 1469 syntax error: postfix/infix operator expected 1470 | p(hello there). 1471 | ^ here 1472 [eclipse 3]: use_module(m). 1473 1474 yes. 1475 [eclipse 4]: p(hello there). 1476 hello there 1477 1478 yes. 1479 1480Error: 1481 module_interface(M). (Error 4). 1482 module_interface(1). (Error 5). 1483 module_interface(a_locked_module). (Error 82). 1484 1485 1486 1487", 1488 see_also:[module/1, begin_module / 1, create_module / 1, erase_module / 1, current_module / 1]]). 1489 1490:- comment(call / 2, [ 1491 summary:"Succeeds if Goal (which is visible in module Module) succeeds. 1492 1493", 1494 amode:call(+,+), 1495 desc:html(" Calls a goal Goal from the module Module. This predicate is used to 1496 call goals whose functors and visibility are known only at the time they 1497 are called. It may be used to implement tool bodies. 1498 1499<P> 1500 Note that !/0 does not cut through call/2. 1501 1502<P> 1503"), 1504 args:["Goal" : "Atom or compound term.", "Module" : "Atom."], 1505 resat:"Resatisfiable if Goal is resatisfiable", 1506 fail_if:"Fails if Goal fails", 1507 exceptions:[4 : "Goal is not instantiated.", 4 : "Module is not instantiated.", 5 : "Goal is neither an atom nor a compound term.", 5 : "Module is not an atom.", 68 : "Goal is an undefined procedure in Module."], 1508 eg:" 1509Success: 1510 [eclipse]: [user]. 1511 :-module(m). 1512 p. 1513 user compiled 28 bytes in 0.00 seconds 1514 yes. 1515 [eclipse]: p. 1516 calling an undefined procedure p in module eclipse 1517 [eclipse]: call(p, m). 1518 yes. 1519 1520Fail: call(fail, any). 1521 1522Error: 1523 call(Var,eclipse). (Error 4). 1524 call(ls,Var). (Error 4). 1525 call(\"write(a)\",eclipse). (Error 5). 1526 call(foo(a),eclipse). (Error 68). 1527 1528 1529 1530", 1531 see_also:[call / 1, (@)/2, (:) / 2]]). 1532 1533:- comment(define_error / 2, [ 1534 summary:"Error number N is newly defined to give the message Message. 1535 1536", 1537 amode:(define_error(+,-) is det), 1538 desc:html(" This predicate is used to define new user error types. Message is a 1539 string which is going to be printed when this error occurs (the string 1540 returned by error_id/2). N is bound to the new error number. The 1541 default error handler for the new error is error_handler/2. 1542 1543<P> 1544 Note that the error numbers should not be hard-coded in subsequent calls 1545 to error/2 etc., as the error numbers are arranged at run time and may 1546 be changed between releases. 1547 1548<P> 1549"), 1550 args:["Message" : "String.", "N" : "Variable."], 1551 exceptions:[4 : "Message is not instantiated.", 5 : "Message is instantiated, but not to a string.", 5 : "N is instantiated."], 1552 eg:" 1553Success: 1554 define_error(\"my first error message\",N). (gives N=340). 1555 define_error(\"my second error message\",N). (gives N=341). 1556 1557 [eclipse]: [user]. 1558 :- define_error(\"1st arg should be number\",N), 1559 setval(usererror, N). 1560 do(N,Res) :-(number(N) -> 1561 Res is sqrt(N) 1562 ; 1563 getval(usererror, Err), 1564 error(Err, do(N,Res))). 1565 user compiled 232 bytes in 0.00 seconds 1566 yes. 1567 [eclipse]: do(4,2.0). 1568 yes. 1569 [eclipse]: do(four,2.0). 1570 1st arg should be number in do(four, 2.0) 1571Error: 1572 define_error(M,N). (Error 4). 1573 define_error(atom,N). (Error 5). 1574 define_error(\"incorrect module\",340). (Error 5). 1575 1576 1577 1578", 1579 see_also:[set_event_handler/2, error_id / 2]]). 1580 1581:- comment(errno_id / 2, [ 1582 summary:"Message is bound to the message string that corresponds to the UNIX message 1583for a system call error when the UNIX errno has the value N. 1584 1585", 1586 amode:(errno_id(+,-) is det), 1587 desc:html(" This predicate unifies Message with the string that corresponds to the 1588 UNIX message for a system call error when errno has the value N. 1589 1590<P> 1591 The errors are system dependent. In SunOS 4.0, there are 89 defined 1592 UNIX system call errors. 1593 1594<P> 1595"), 1596 args:["N" : "Positive integer.", "Message" : "Variable."], 1597 exceptions:[4 : "N is not instantiated.", 5 : "N is instantiated, but not to an integer.", 5 : "Message is instantiated."], 1598 eg:" 1599Success: 1600 % the following sample errors are for SunOS 4.0 1601 errno_id(1,M). (gives M = \"Not owner\"). 1602 errno_id(2,M). (gives M = \"No such file or directory\"). 1603 errno_id(3,M). (gives M = \"No such process\"). 1604 errno_id(4,M). (gives M = \"Interrupted system call\"). 1605 errno_id(5,M). (gives M = \"I/O error\"). 1606 errno_id(6,M). (gives M = \"No such device or address\"). 1607 errno_id(89,M). (gives M = \"Remote address changed\"). 1608 errno_id(90,M). (gives M = \"Unknown system error\"). 1609 % the latter occurs for all errors greater than 89. 1610Error: 1611 errno_id(N,M). (Error 4). 1612 errno_id(1.0,M). (Error 5). 1613 errno_id(1,\"message\"). (Error 5). 1614 1615 1616", 1617 see_also:[errno_id/1]]). 1618 1619:- comment(fail_if / 1, [ 1620 summary:"Succeeds if Goal cannot be satisfied. Uses negation as failure (synonym of 1621not/1 and \\+/1). 1622 1623", 1624 amode:(fail_if(+) is semidet), 1625 desc:html(" Used to fail if Goal succeeds. Uses the standard Prolog form of 1626 negation as failure. 1627 1628<P> 1629 To check whether a call Goal succeeds without binding variables, the 1630 call fail_if( fail_if( Goal)) can be used. 1631 1632<P> 1633 Not that !/0 does not cut through fail_if/1. Unlike not/1 and \\+/1, 1634 fail_if/1 is a protected predicate and cannot be redefined. 1635 1636<P> 1637"), 1638 args:["Goal" : "Atom or compound term."], 1639 fail_if:"Fails if Goal succeeds", 1640 eg:" 1641Success: 1642 fail_if(fail). 1643 fail_if(1 == 2). 1644 fail_if(X == 1). 1645 fail_if(fail_if(X = 1)). 1646 % does not bind X 1647 1648Fail: 1649 fail_if(X = 1). 1650 fail_if(true). 1651 fail_if(3 == 3). 1652 1653 1654 1655", 1656 see_also:[(\+) / 1, (not) / 1, (~) / 1]]). 1657 1658:- comment(reset_error_handler / 1, [ 1659 summary:"Resets the handler for error number Number to its default value. 1660 1661", 1662 amode:(reset_error_handler(+) is det), 1663 desc:html(" The error handler for the specified error number is reset to its default 1664 value, cancelling any previous redefinition. 1665 1666<P> 1667 The errors which exist are implementation defined. 1668 1669<P> 1670"), 1671 args:["Number" : "Integer."], 1672 exceptions:[4 : "Number is not instantiated.", 5 : "Number is instantiated, but not to an integer.", 6 : "Number is not a valid error number."], 1673 eg:" 1674Success: 1675 [eclipse]: string_list(S,L). 1676 instantiation fault in string_list(_g50, _g52) 1677 [eclipse]: set_error_handler(4,true/0), string_list(S,L). 1678 S = _g56 1679 L = _g58 1680 yes. 1681 [eclipse]: reset_error_handler(4), string_list(S,L). 1682 instantiation fault in string_list(_g62, _g64) 1683 1684Error: 1685 reset_error_handler(N). (Error 4). 1686 reset_error_handler(5.0). (Error 5). 1687 reset_error_handler(1000). (Error 6). 1688 1689 1690 1691", 1692 see_also:[reset_event_handler / 1]]). 1693 1694:- comment((delay) / 2, [ 1695 summary:"Delay the Goal on all variables in the term Variables. 1696 1697", 1698 amode:(delay(?,+) is det), 1699 desc:html(" The specified goal Goal is made a suspended goal such that it will be 1700 woken whenever any of the variables in the term Variables is bound (even 1701 to another variable). This predicate is obsolete, a more precise 1702 control over suspending and waking is obtained using make_suspension/3 1703 and insert_suspension/3,4 and with the suspend.pl library. 1704 1705<P> 1706"), 1707 args:["Variables" : "Any Prolog term.", "Goal" : "A callable term."], 1708 exceptions:[4 : "Goal is not instantiated.", 5 : "Goal is not a callable term.", 60 : "Goal does not refer to an existing procedure."], 1709 eg:" 1710[eclipse 1]: delay(X, writeln(hello)). 1711 1712X = X 1713 1714Delayed goals: 1715 writeln(hello) 1716yes. 1717[eclipse 2]: delay(X, writeln(hello)), 1718 writeln(one), 1719 X=1, % causes waking 1720 writeln(two). 1721one 1722hello 1723two 1724 1725X = 1 1726yes. 1727[eclipse 3]: delay([X,Y], writeln(X)), X=Y. 1728X 1729 1730X = X 1731Y = X 1732yes. 1733 1734 1735", 1736 see_also:[suspend/3, make_suspension / 3, insert_suspension / 3]]). 1737 1738:- comment(schedule_woken / 1, [ 1739 summary:"Pass the suspension list SuspList to the waking scheduler. 1740 1741", 1742 amode:(schedule_woken(++) is det), 1743 desc:html(" Suspensions in ECLiPSe are executed in two stages: first the suspension 1744 is processed by the waking scheduler which puts it into a global 1745 priority list where it waits until the wake/0 predicate is called by a 1746 predicate which is running with lower priority than the priority of the 1747 suspension. The predicate schedule_woken/1 is the interface to the 1748 waking scheduler. It accepts a list or a difference list of 1749 suspensions. Executed suspensions are ignored, sleeping suspensions are 1750 inserted into the corresponding priority list. 1751 1752<P> 1753"), 1754 args:["SuspList" : "Suspension list or difference list or variable"], 1755 exceptions:[5 : "SuspList is not a list nor a difference list nor free."], 1756 eg:" 1757[eclipse 1]: make_suspension(writeln(hello), 1, S), 1758 schedule_woken([S]), wake. 1759hello 1760 1761S = 'WOKEN GOAL' 1762yes. 1763[eclipse 2]: make_suspension(writeln(hello), 255, S), 1764 schedule_woken([S]), wake. 1765 1766S = 'GOAL'(writeln(hello), eclipse) 1767 1768Delayed goals: 1769writeln(hello) 1770yes. 1771 1772 1773 1774", 1775 see_also:[schedule_suspensions/2, insert_suspension / 3, insert_suspension / 4, is_suspension / 1, suspension_to_goal / 3, wake / 0]]). 1776 1777:- comment(set_suspension_priority / 2, [ 1778 summary:"Change the priority of the suspended goal Susp to Priority. 1779 1780", 1781 amode:(set_suspension_priority(+,+) is det), 1782 desc:html(" Every suspended goal has an associated priority. The initial priority 1783 is specified when the suspension is created with make_suspension/3. 1784 The priority can be changed anytime, but when the suspension has 1785 already been scheduled for execution (by schedule_suspensions/2), 1786 the change has no effect on this already scheduled execution. 1787 1788<P> 1789 Changing priorities is most useful for demons (where the same 1790 suspension is used for arbitrary many wakings) and where one might 1791 like to vary its urgency. Typically, the cheaper a goal is, and 1792 the more likely it is to fail or to produce useful information, 1793 the higher should it priority be. However, the relative priorities 1794 of other suspended goals must be kept in mind as well. 1795 1796<P> 1797 Note that a suspension is not a standard Prolog data structure and can 1798 only be manipulated in a restricted way. 1799 1800<P> 1801"), 1802 args:["Susp" : "A variable", "Priority" : "A small integer"], 1803 exceptions:[4 : "Susp or Priority are not instantiated.", 5 : "Susp is not a live suspension or Priority is not an integer.", 6 : "Priority is not a valid priority."], 1804 eg:" 1805 1806 1807 1808", 1809 see_also:[set_suspension_data/3, (demon) / 1, is_suspension / 1, kill_suspension / 1, make_suspension / 3, schedule_suspensions / 2, suspension_to_goal / 3]]). 1810 1811:- comment(set_error_handler / 2, [ 1812 summary:"Set an error handler PredSpec for the error with number Number. 1813 1814", 1815 amode:(set_error_handler(+,++) is det), 1816 desc:html(" Assigns the procedure specified by PredSpec (specified as name/arity) as 1817 the error handler for the error whose number is given by Number. 1818 1819<P> 1820 An error handler such as PredSpec can have 3 optional arguments: the 1821 1st argument is the number of the error; the 2nd argument is the culprit 1822 (a structure corresponding to the call which caused it); the 3rd is the 1823 caller module or a free variable (if the module is unknown). The error 1824 handler is free to use less than 3 arguments. 1825 1826<P> 1827 The errors which exist are implementation defined. 1828 1829<P> 1830"), 1831 args:["Number" : "Integer.", "PredSpec" : "Term of the form Atom/Integer."], 1832 exceptions:[4 : "Either Number or PredSpec is not instantiated.", 5 : "Number is not an integer.", 5 : "PredSpec is not of the form Atom/Integer.", 6 : "Number is not a valid error number.", 6 : "PredSpec is of the form Atom/Integer, but the integer is greater than 3.", 60 : "PredSpec is of the form Atom/Integer, but no such predicate has been defined."], 1833 eg:" 1834Success: 1835 [eclipse]: string_list(S,L). 1836 instantiation fault in string_list(_g50, _g52) 1837 [eclipse]: get_error_handler(4,M,N). 1838 M = error_handler/2 1839 N = sepia_kernel 1840 yes. 1841 [eclipse]: set_error_handler(4,true/0), string_list(S,L). 1842 S = _g56 1843 L = _g58 1844 yes. 1845 1846 [eclipse]: [user]. 1847 a :- write(warning_output, \"typo\"), fail. 1848 user compiled 100 bytes in 0.03 seconds 1849 [eclipse]: set_error_handler(5,a/0). 1850 yes. 1851 [eclipse]: atom_length(\"atom\",L). 1852 typo 1853 no. 1854 1855Error: 1856 set_error_handler(N,true/0). (Error 4). 1857 set_error_handler(5,P). (Error 4). 1858 set_error_handler(5.0,true/0). (Error 5). 1859 set_error_handler(1000,X). (Error 6). 1860 set_error_handler(-1,X). (Error 6). 1861 set_error_handler(6,a/4). (Error 6). % arity > 3. 1862 set_error_handler(6,t/2). (Error 60). % no t/2. 1863 1864 1865 1866", 1867 see_also:[set_event_handler/2, get_error_handler / 3]]). 1868 1869:- comment(get_timer / 2, [ 1870 summary:"Succeed if the specified Timer is running and sends signals in intervals of 1871Interval seconds. 1872 1873", 1874 amode:(get_timer(+,-) is semidet), 1875 desc:html(" Used to examine the states of the 3 system interval timers. When the 1876 specified timer is switched off, the predicate fails. Otherwise, the 1877 Interval argument is unified with a float number indicating the timer 1878 interval in seconds. The names of the timers are real, virtual and 1879 profile. 1880 1881<P> 1882"), 1883 args:["Timer" : "One of the atoms real, virtual or profile.", "Interval" : "A variable or a float number."], 1884 fail_if:"Fails if the timer is not running", 1885 exceptions:[4 : "Timer is not instantiated.", 5 : "Timer is not an atom.", 6 : "Timer is an atom not naming a timer.", 5 : "Interval neither a variable nor a float number."], 1886 eg:" 1887[eclipse 1]: set_timer(virtual, 9), get_timer(virtual, I). 1888 1889I = 9.0 1890yes. 1891[eclipse 2]: set_timer(virtual, 0), get_timer(virtual, I). 1892 1893no (more) solution. 1894 1895 1896 1897", 1898 see_also:[event_after/2, event_after_every/2, alarm / 1, current_interrupt / 2, sleep / 1, set_interrupt_handler / 2, set_timer / 2]]). 1899 1900:- comment(set_timer / 2, [ 1901 summary:"Start (or stop) the specified Timer to send signals in intervals of 1902Interval seconds. 1903 1904", 1905 amode:(set_timer(+,+) is det), 1906 desc:html(" Used to initialise one of the 3 operating system's interval timers. 1907 After a call to this predicate, the corresponding timer will start 1908 sending signals to the ECLiPSe process every Interval seconds. Every 1909 call will change the previous interval of the specified timer. A timer 1910 is switched off by setting its Interval to 0. 1911 1912<P> 1913<PRE> 1914 ----------------- 1915 |Timer |Signal | 1916 ----------------- 1917 |real |alrm | 1918 |virtual |vtalrm | 1919 |profile |prof | 1920 ----------------- 1921</PRE> 1922"), 1923 args:["Timer" : "One of the atoms real, virtual or profile.", "Interval" : "Number (integer or float)"], 1924 exceptions:[4 : "Timer orInterval is not instantiated.", 5 : "Timer is not an atom.", 5 : "Interval is not integer or float.", 6 : "Timer is an atom not naming a timer.", 170 : "Interval is an out of range timer interval."], 1925 eg:" 1926[eclipse]: [user]. 1927 handler(N) :- 1928 getval(count, Count), 1929 writeln(signal(N)-Count), 1930 ( Count > 0 -> 1931 decval(count) 1932 ; 1933 set_timer(real, 0) % switch off the timer 1934 ). 1935 1936 :- set_interrupt_handler(alrm, handler/1). 1937 user compiled traceable 372 bytes in 0.00 seconds 1938 1939yes. 1940[eclipse]: setval(count, 4), set_timer(real, 0.5). 1941 1942yes. 1943[eclipse]: signal(14) - 4 1944signal(14) - 3 1945signal(14) - 2 1946signal(14) - 1 1947signal(14) - 0 1948 1949 1950 1951", 1952 see_also:[event_after/2, event_after_every/2, alarm / 1, current_interrupt / 2, get_timer / 2, sleep / 1, set_interrupt_handler / 2]]). 1953 1954:- comment(global_op / 3, [ 1955 summary:"Defines the global operator(s) in Name to have precedence Precedence and 1956associativity Associativity. If Precedence is 0 then the operator 1957definition is removed. 1958 1959", 1960 amode:(global_op(+,+,++) is det), 1961 desc:html(" Defines Name as an operator of precedence Precedence and associativity 1962 Associativity. Name may be a single operator or a list of operators, in 1963 which each is given the specified precedence and associativity. 1964 1965<P> 1966 The operator is defined to be globally available, ie. visible in every 1967 module, unless hidden by a local operator. 1968 1969<P> 1970 Precedence is an integer in the range 0 to 1200. If the precedence is 0 1971 the definition of the operator is removed. 1972 1973<P> 1974 Associativity must be one of the following atoms: 1975 1976<P> 1977<PRE> 1978 xfx infix 1979 xfy infix 1980 yfx infix 1981 fx prefix 1982 fy prefix 1983 xf postfix 1984 yf postfix 1985</PRE> 1986 x represents an argument whose precedence must be lower than that of the 1987 operator. y represents an argument whose precedence must be lower or 1988 equal to that of the operator. 1989 1990<P> 1991 Prefix, infix and postfix operators are independent of each other and 1992 may coexist. See the manual chapter on syntax about how ambiguities are 1993 resolved in this case. 1994 1995<P> 1996"), 1997 args:["Precedence" : "Integer", "Associativity" : "Atom", "Name" : "Atom or List of atoms"], 1998 exceptions:[4 : "Any of the input arguments is uninstantiated.", 5 : "Precedence is not an integer.", 5 : "Name is not an atom or list of atoms.", 6 : "Precedence is not in range 0 to 1200.", 6 : "Associativity is not xf, xfx, fy etc.", 43 : "Multiple definition of postfix and infix for Name."], 1999 eg:" 2000Success: 2001 [eclipse]: global_op(100,fx,hello). % define prefix operator 2002 2003 yes. 2004 [eclipse]: read(X). 2005 > hello david. % read using operator 2006 2007 X = hello david 2008 yes. 2009 [eclipse]: global_op(200, xfy, -+-), 2010 global_op(300, fx, -+-). % multiple infix/prefix 2011 2012 yes. 2013 [eclipse]: global_op(100,xfx,[a,b,c,d]). % define list of op's 2014 2015 yes. 2016 [eclipse]: current_op(100,xfx,Y). % return defined op's 2017 2018 Y = d More? (;) 2019 2020 Y = a More? (;) 2021 2022 Y = c More? (;) 2023 2024 Y = b More? (;) % RETURN pressed 2025 2026 yes. 2027 [eclipse]: global_op(300,xfy,?), global_op(300,yfx,:). 2028 2029 yes. 2030 [eclipse]: display(a ? b ? c), display(a : b : c). 2031 ?(a, ?(b, c)) % xfy operator 2032 2033 :(:(a, b), c) % yfx operator 2034 yes. 2035 [eclipse]: 2036 2037Error: 2038 global_op(X,fx,aaa). (Error 4) 2039 global_op(a,fx,aaa). (Error 5) 2040 global_op(100,xfx,1). (Error 5) 2041 global_op(100,abc,fred). (Error 6) 2042 2043 global_op(100,xfx,aaa),global_op(100,xf,aaa). (Error 43) 2044 2045 2046 2047", 2048 see_also:[current_op / 3, op / 3]]). 2049 2050:- comment(call_explicit / 2, [ 2051 summary:"Succeeds if Goal which is defined in module Module succeeds. 2052 2053", 2054 amode:call_explicit(+,+), 2055 desc:html(" This predicate provides a means to override the module system's 2056 visibility rules. While the builtins call/1 and call/2 call the 2057 predicate that is visible from a certain module, call_explicit/2 allows 2058 to call a predicate which is defined in a certain module. This allows 2059 calling a predicate that is otherwise not visible in the caller module. 2060 The most plausible use of this feature is to allow local redefinition of 2061 a predicate using the existing definition in the implementation. 2062 2063<P> 2064 Note that call_explicit can only call exported or global predicates in 2065 order to preserve module privacy. 2066 2067<P> 2068"), 2069 args:["Goal" : "Atom or compound term.", "Module" : "Atom."], 2070 resat:"Resatisfiable if Goal is resatisfiable", 2071 fail_if:"Fails if Goal fails", 2072 exceptions:[4 : "Goal is not instantiated.", 4 : "Module is not instantiated.", 5 : "Goal is neither an atom nor a compound term.", 5 : "Module is not an atom.", 68 : "Goal is an undefined procedure in Module."], 2073 eg:" 2074Success: 2075 [eclipse]: cd(~). 2076 system interface error: 2077 No such file or directory in cd(~) 2078 2079 [eclipse]: [user]. % redefine cd/1, using its 2080 % original definition 2081 cd(~) :- !, 2082 getenv('HOME', Home), 2083 call_explicit(cd(Home), sepia_kernel). 2084 cd(Dir) :- 2085 call_explicit(cd(Dir), sepia_kernel). 2086 2087 [eclipse]: cd(~). 2088 yes. 2089 2090Fail: 2091 call_explicit(fail, sepia_kernel). 2092 2093Error: 2094 call_explicit(Var,eclipse). (Error 4). 2095 call_explicit(ls,Var). (Error 4). 2096 call_explicit(\"write(a)\",eclipse). (Error 5). 2097 call_explicit(foo(a),eclipse). (Error 68). 2098 2099 2100 2101", 2102 see_also:[(:)/2, call / 1, (@) / 2]]). 2103 2104:- comment(coroutine / 0, [ 2105 summary:"Switches on the coroutine flag, equivalent to set_flag(coroutine, on). 2106 2107", 2108 amode:(coroutine is det), 2109 desc:html(" Used to switch the global coroutine-flag to on. This causes a subset of 2110 the built-in predicates not to raise instantiation faults any longer but 2111 to delay instead. This concerns all sufficiently logical predicates 2112 like the arithmetic built-ins, functor/3, arg/3, and many others. 2113 2114<P> 2115"), 2116 eg:" 2117[eclipse 1]: X>0. 2118instantiation fault in X > 0 2119[eclipse 2]: coroutine. 2120 2121yes. 2122[eclipse 3]: X>0. 2123 2124X = X 2125 2126Delayed goals: 2127 X > 0 2128yes. 2129 2130 2131 2132", 2133 see_also:[set_flag / 2]]). 2134 2135 2136 2137:- comment(is_locked / 1, [ 2138 summary:"Succeeds if the module Module is locked. 2139 2140", 2141 amode:(is_locked(+) is semidet), 2142 desc:html(" Used to test whether the module Module is locked. 2143 2144<P> 2145"), 2146 args:["Module" : "Atom."], 2147 fail_if:"Fails if the module Module is not locked", 2148 exceptions:[4 : "Module is not instantiated.", 2149 5 : "Module is instantiated, but not to an atom.", 2150 80 : "Module is not a module."], 2151 eg:" 2152Success: 2153 [eclipse]: create_module(m). 2154 yes. 2155 [eclipse]: lock(m, \"pass\"). 2156 yes. 2157 [eclipse]: module(m). 2158 trying to access a locked module in module(m) 2159 [eclipse]: is_locked(m), unlock(m, \"pass\"). 2160 yes. 2161 [eclipse]: is_locked(m). 2162 no. 2163 [eclipse]: module(m). 2164 [m]: 2165Error: 2166 is_locked(M). (Error 4). 2167 is_locked(1). (Error 5). 2168 is_locked(not_a_module). (Error 80). 2169 2170 2171 2172", 2173 see_also:[lock / 1, lock / 2, unlock / 2, get_module_info/3]]). 2174 2175 2176:- comment(b_external / 2, [ 2177 summary:"Defines PredSpec to be a nondeterministic external predicate linked to the 2178C function whose system name is CName. 2179 2180", 2181 amode:(b_external(++,+) is det), 2182 desc:html(" Declares the PredSpec to be a non-deterministic Prolog predicate (in the 2183 caller module) linked to the ``C'' function whose system name is CName. 2184 2185<P> 2186 If the visibility of PredSpec is not declared, it is set to local. 2187 2188<P> 2189 If necessary, an underscore is prepended to CName to get its form as 2190 used by the C compiler. 2191 2192<P> 2193 If a call to PredSpec has already been compiled as a deterministic 2194 external call, error 62 is raised (``inconsistent procedure 2195 redefinition''). This can be prevented by defining the external before 2196 compiling any call to it or by using the declaration predicate 2197 b_external/1. 2198 2199<P> 2200"), 2201 args:["PredSpec" : "Of the form Atom/Integer (predicate name/arity).", "CName" : "Atom or a string."], 2202 exceptions:[4 : "Either PredSpec or CName is not instantiated.", 5 : "PredSpec is not of the form Atom/Integer.", 5 : "CName is not an atom or a string.", 62 : "A call to PredSpec has already been compiled as a deterministic external call.", 211 : "External function does not exist."], 2203 eg:" 2204 2205 % file to create an external predicate. 2206 % cat sin.c 2207 2208 % external.h contains the macros for the external interface. 2209 #include \"external.h\" 2210 #include <math.h> 2211 2212 p_sines(vel, tel, vlist, tlist) 2213 value vel, vlist; 2214 type tel, tlist; 2215 { 2216 pword *p; 2217 2218 Error_If_Ref(tlist); 2219 if (IsNil(tlist)) 2220 { 2221 Fail; 2222 } 2223 Check_List(tlist); 2224 p = vlist.ptr + 1; 2225 Dereference(p); 2226 Remember(2, p->val, p->tag); 2227 Dereference(vlist.ptr); 2228 Check_Float(vlist.ptr->tag); 2229 Return_Unify_Float(vel, tel, 2230 (float)sin(((vlist.ptr->val.real)*3.1415926535)/180.0)); 2231 } 2232 2233 % compile with ECLiPSe include files. 2234 % cc -c -I/usr/local/ECLIPSE/include sin.c 2235 % eclipse 2236 2237 % load the .o file dynamically into the system with math option. 2238 [eclipse]: load('sin.o',\"-lm\"). 2239 yes. 2240 2241 % link the object file with a predicate definition. 2242 [eclipse]: b_external(sines/2,p_sines). 2243 yes. 2244 2245 % check on existence and flags of sines/2. 2246 [eclipse]: get_flag(sines/2, type, T), 2247 get_flag(sines/2, call_type, C_type), 2248 get_flag(sines/2, visibility, Vis). 2249 T = user 2250 C_type = b_external 2251 Vis = local More? (;) 2252 yes. 2253 2254 % use sines/2. 2255 [eclipse]: sines(E,[0.0,45.0,90.0,270.0]). 2256 E = 0.0 More? (;) 2257 E = 0.707107 More? (;) 2258 E = 1.0 More? (;) 2259 E = -1.0 More? (;) 2260 no (more) solution. 2261 2262Error: 2263 b_external(p/0, S). (Error 4). 2264 b_external(PredSpec, p_pred). (Error 4). 2265 b_external(\"p/0\", p_p0). (Error 5). 2266 b_external(p/0, 123). (Error 5). 2267 2268 [eclipse]: [user]. 2269 :- external(a/0, c_a). % should use b_external/1. 2270 p :- a. 2271 user compiled 60 bytes in 0.00 seconds 2272 yes. 2273 [eclipse]: b_external(a/0, c_a). (Error 62). 2274 2275 2276 b_external(mess/1,\"p_messg\"). (Error 211). 2277% call load/1,2 first. 2278 2279 2280 2281", 2282 see_also:[external / 1, external / 2, b_external / 1, load / 1]]). 2283 2284:- comment(b_external / 1, [ 2285 summary:"Declares PredSpec to be a non-deterministic external predicate. 2286 2287", 2288 amode:(b_external(++) is det), 2289 desc:html(" Declares the (may be not yet visible) predicate PredSpec to be a 2290 non-deterministic external predicate. 2291 2292<P> 2293 This declaration is needed to compile calls to an external predicate 2294 before it is actually defined with b_external/2. 2295 2296<P> 2297"), 2298 args:["PredSpec" : "Of the form Atom/Integer (predicate name/arity)."], 2299 exceptions:[4 : "PredSpec is not instantiated.", 5 : "PredSpec is not of the form Atom/Integer.", 62 : "A call to PredSpec has already been compiled as a deterministic external call."], 2300 eg:" 2301Success: 2302 2303 % compiling a call to an external before its definition (see description 2304 % of b_external/2 for detail on creating external predicates). 2305 [eclipse]: [user]. 2306 :- import sines/2 from trig_lib. 2307 :- b_external(sines/2). % declare its call_type 2308 p(Values) :- sines(Res, Values), writeln(Res), fail. 2309 p(_). 2310 user compiled 216 bytes in 0.03 seconds 2311 2312 % definition of sines/2 will not raise an inconsistent type definition 2313 % thanks to the proper declaration above. 2314 [eclipse]: sh(\"cat trig_lib.pl\"). 2315 :- module(trig_lib). 2316 :- load('sin.o', \"-lm\"). % see example in b_external/2 2317 :- b_external(sines/2, p_sines). 2318 :- export sines/2. 2319 2320 yes 2321 [eclipse]: [trig_lib]. 2322 trig_lib.pl compiled 0 bytes in 0.18 seconds 2323 yes. 2324 [eclipse]: p([0.0,45.0,90.0,270.0]). 2325 0.0 2326 0.707107 2327 1.0 2328 -1.0 2329 yes. 2330 2331Error: 2332 b_external(PredSpec). (Error 4). 2333 b_external(\"p/0\"). (Error 5). 2334 2335 [eclipse]: [user]. 2336 :- external(a/0). 2337 p :- a. 2338 user compiled 32 bytes in 0.00 seconds 2339 yes. 2340 [eclipse]: b_external(a/0). (Error 62). 2341 2342 2343 2344", 2345 see_also:[external / 1, b_external / 2, external / 2, load / 1]]). 2346 2347:- comment(get_error_handler / 3, [ 2348 summary:"Returns the error_handler for error number Number and its home module 2349Module. 2350 2351", 2352 amode:(get_error_handler(+,-,-) is det), 2353 desc:html(" Given the error number Number, PredSpec is unified with the specification 2354 (i.e. a term of the form name/arity) of the current handler for error 2355 with number Number; Module is unified with its home module. 2356 2357<P> 2358 The errors which exist are implementation defined. 2359 2360<P> 2361"), 2362 args:["Number" : "Integer.", "PredSpec" : "Term which unifies with atom/integer.", "Module" : "Atom or variable."], 2363 exceptions:[4 : "Number is not instantiated.", 5 : "Number is not an integer.", 5 : "PredSpec is neither a variable nor of the form Atom/Integer.", 6 : "Number is not a valid error number."], 2364 eg:" 2365Success: 2366 [eclipse]: string_list(S,L). 2367 instantiation fault in string_list(_g50, _g52) 2368 [eclipse]: get_error_handler(4,M,N). 2369 M = error_handler/2 2370 N = sepia_kernel 2371 yes. 2372 [eclipse]: set_event_handler(4,true/0), string_list(S,L). 2373 > get_error_handler(4,true/0,sepia_kernel). 2374 S = _g56 2375 L = _g58 2376 yes. 2377Fail: 2378 get_error_handler(4, error/2, sepia_kernel). 2379 2380 [eclipse]: set_event_handler(4,true/0), 2381 > get_error_handler(4,error_handler/2,M). 2382 no. 2383Error: 2384 get_error_handler(N,true/0,sepia_kernel). (Error 4). 2385 get_error_handler(5,1.2,sepia_kernel). (Error 5). 2386 get_error_handler(5.0,true/0,sepia_kernel). (Error 5). 2387 get_error_handler(1000,X, sepia_kernel). (Error 6). 2388 get_error_handler(-1,X,sepia_kernel). (Error 6). 2389 get_error_handler(6,t/0,\"sepia_kernel\"). (Error 6). 2390 2391 2392 2393", 2394 see_also:[set_event_handler / 2, error / 2, error / 3, error_id / 2]]). 2395 2396:- comment(current_struct / 1, [ 2397 summary:"Succeeds if Struct is a currently visible structure specification. 2398 2399", 2400 amode:(current_struct(+) is semidet), 2401 amode:(current_struct(-) is nondet), 2402 desc:html(" Used to retrieve the definition of a defined structure, or to 2403 enumerate all visible structure definitions. 2404 2405<P> 2406"), 2407 args:["Struct" : "Variable or structure."], 2408 fail_if:"There is no declared structure with Struct's functor", 2409 exceptions:[5 : "Struct is neither variable nor structure."], 2410 eg:" 2411 [eclipse 1]: local struct(employee(name,age,salary)). 2412 yes. 2413 2414 [eclipse 2]: current_struct(employee(A,B,C)). 2415 A = name 2416 B = age 2417 C = salary 2418 yes. 2419 2420 [eclipse 3]: Emp = employee{}, current_struct(Emp). 2421 Emp = employee(name, age, salary) 2422 yes. 2423 2424 [eclipse 4]: current_struct(S). 2425 S = employee(name, age, salary) More? (;) 2426 S = suspend(inst, constrained, bound) 2427 yes. 2428 2429Error: 2430 current_struct(a). (Error 5). 2431 2432 2433 2434", 2435 see_also:[current_struct/2, (local) / 1, struct / 1]]). 2436 2437:- comment(char_int / 2, [ 2438 summary:"Succeeds if Integer is the ASCII code of the one-character string Char. 2439 2440", 2441 amode:(char_int(+,-) is det), 2442 amode:(char_int(-,+) is det), 2443 desc:html(" If Char is instantiated, converts it to its corresponding ASCII code. 2444 2445<P> 2446 If Integer is instantiated, converts it to its corresponding 2447 one-character string. 2448 2449<P> 2450"), 2451 args:["Char" : "One-character string or variable.", "Integer" : "Integer (in the range 0 to 255) or variable."], 2452 exceptions:[5 : "Char is instantiated, but not to a 1-character string.", 5 : "Integer is instantiated, but not to an integer.", 6 : "Integer is instantiated to an integer outside the range 0 to 255.", 4 : "Neither Char nor Integer are instantiated (non-coroutine mode only)."], 2453 eg:" 2454 Success: 2455 char_int(\"b\",98). 2456 char_int(C,99). (gives C=\"c\"). 2457 char_int(\"a\",I). (gives I=97). 2458 Fail: 2459 char_int(\"a\",98). 2460 Error: 2461 char_int(C,I). (Error 4). 2462 char_int(\"ab\",I). (Error 5). 2463 char_int('a',I). (Error 5). 2464 char_int(C,'30'). (Error 5). 2465 char_int(C,128). (Error 6). 2466 2467 2468 2469", 2470 see_also:[char_code/2, get_char / 1, get_char / 2, put_char / 1, put_char / 2, string_list / 2, string_list / 3]]). 2471 2472:- comment(is_built_in / 1, [ 2473 summary:"Succeeds if PredSpec is a system built-in predicate. 2474 2475", 2476 amode:(is_built_in(++) is semidet), 2477 desc:html(" Used to test whether PredSpec is a ECLiPSe built-in predicate. 2478 2479<P> 2480 This predicate only succeeds for a PredSpec which is known to be a 2481 built-in. Undefined Predspec's raise an exception. 2482 2483<P> 2484"), 2485 args:["PredSpec" : "Term of the form Atom/Integer."], 2486 fail_if:"Fails if PredSpec is not a built-in predicate", 2487 exceptions:[4 : "PredSpec is not fully instantiated.", 5 : "PredSpec is not in the format Atom/Integer.", 60 : "PredSpec is not a defined procedure."], 2488 eg:" 2489Success: 2490 is_built_in(nl/0). 2491 is_built_in(write/1). 2492 2493Fail: 2494 is_built_in(append/3). % append/3 is a library 2495 % predicate, not a built-in. 2496Error: 2497 is_built_in(X). (Error 4). 2498 is_built_in(a/X). (Error 4). 2499 is_built_in(a). (Error 5). 2500 is_built_in(1). (Error 5). 2501 is_built_in(undefined/0). (Error 60). 2502 2503 2504 2505", 2506 see_also:[current_built_in / 1, is_predicate / 1, get_flag / 3]]). 2507 2508 2509:- comment(current_after_event / 1, [ 2510 summary:" Check or find currently pending after events (inside handler). 2511 2512", 2513 amode:(current_after_event(+) is semidet), 2514 amode:(current_after_event(-) is det), 2515 desc:html("\ 2516 2517 If Event is an atom, succeeds if Event is a currently pending after 2518 event, i.e. an event which is setup by either event_after/2 or 2519 event_after_every/2, and which is waiting to be raised 2520 (event_after_every/2 will always be pending as it is raised 2521 repeatedly). If Event is a variable, then all the currently pending 2522 events are returned as a list. An event will appear as many times as it 2523 had been setup. 2524 2525<P> 2526 Note that this predicate can only be called from within an after event 2527 handler, i.e. when the timer is paused, and the after event state can be 2528 safely examined. An error would be raised otherwise. 2529<P> 2530"), 2531 args:["Event" : "Atom or variable"], 2532 fail_if:"Fails if Event is not a pending after event", 2533 exceptions:[1 : "Predicate is called while after events was not frozen.", 2534 5 : "Event is not an atom or variable."], 2535 eg:" 2536 setup :- 2537 set_event_handler(hi, hi/0), 2538 event_after_every(hi, 3.2). 2539 2540 hi :- 2541 current_after_event(Es), 2542 writeln(hi), 2543 writeln('Pending events'-Es). 2544 2545 :- setup, repeat, fail. 2546 % just spinning after the setup for events to be raised. 2547 2548", 2549 see_also:[event_after / 2, event_after_every / 2, event / 1, set_event_handler / 2, cancel_after_event / 1]]). 2550 2551 2552:- comment(cancel_after_event / 1, [ 2553 summary:" Cancel all pending instances of after event Event. 2554 2555", 2556 amode:(cancel_after_event(+) is semidet), 2557 desc:html(" All instances of the pending after event Event is 2558 cancelled so that the event will not be triggered. A pending after event 2559 is an event which is setup by either event_after/2, event_after/3 or 2560 event_after_every/2, and which is waiting to be raised 2561 (event_after_every/2 will always be pending as it is raised repeatedly). 2562 2563<P> 2564 Note that the processing of an already raised, but as yet unprocessed 2565 event will not be cancelled by this predicate. 2566 2567<P> 2568 This is equivalent to 2569<PRE> 2570 cancel_after_event(Event) :- 2571 cancel_after_event(Event, [_|_]). 2572</PRE> 2573"), 2574 args:["Event" : "Atom"], 2575 fail_if:"Fails if Event is not a pending after event", 2576 exceptions:[5 : "Event is not an atom."], 2577 eg:" 2578 setup :- 2579 set_event_handler(hi, hi/0), 2580 event_after_every(hi, 3.2). 2581 2582 hi :- 2583 writeln(hi). 2584 2585 kill :- 2586 ( cancel_after_event(hi) -> 2587 writeln('event cancelled') 2588 ; 2589 writeln('no event to cancel') 2590 ). 2591", 2592 see_also:[cancel_after_event / 2, event_after / 2, event_after / 3, 2593 event_after_every / 2, event / 1, set_event_handler / 2, 2594 current_after_events / 1]]). 2595 2596 2597:- comment(portray_goal / 2, [ 2598 summary:"Apply the goal portray (write macro) transformation to Term", 2599 amode:(portray_goal(+,-) is det), 2600 desc:html("\ 2601 Applies the goal-portray-transformation to Term, if any is visible in the 2602 caller module. If no transformation is visible, TransTerm is identical 2603 to Term. 2604 <P> 2605 This predicate is intended mainly for testing purposes, because 2606 portray-transformations are normally performed implicitly by the 2607 term output predicates write/1,2, writeln/1,2, print/1,2, 2608 display/1,2, printf/2,3 or write_term/2,3. 2609 <P> 2610 This predicate can defined in terms of portray_term/3 as 2611 <PRE> 2612 portray_goal(Term, TransTerm) :- 2613 portray_term(Term, TransTerm, goal). 2614 </PRE> 2615 and is therefore deprecated. 2616"), 2617 args:["Term" : "A callable term.", 2618 "TransTerm" : "A variable or callable term."], 2619 eg:" 2620 [eclipse 1]: lib(fd). 2621 yes. 2622 2623 [eclipse 4]: X#>Y, delayed_goals([G]), portray_goal(G, PG)@fd. 2624 X = X{[-9999999..10000000]} 2625 Y = Y{[-10000000..9999999]} 2626 G = gec(X{[-9999999..10000000]}, -1, Y{[-10000000..9999999]}, -1) 2627 PG = X{[-9999999..10000000]} - Y{[-10000000..9999999]}#>=1 2628 2629 Delayed goals: 2630 X{[-9999999..10000000]} - Y{[-10000000..9999999]}#>=1 2631 yes. 2632", 2633 see_also:[portray_term/3, expand_goal/2, portray/3]]). 2634 2635 2636:- comment(event_create / 2, [ 2637 summary:"Create an ECLiPSe event from an arbitrary goal.", 2638 desc:html("\ 2639 This creates an event from the goal provided, which can be raised 2640 with the standard event handling predicates (e.g. event / 1, event_after / 2 2641 and event_after_every / 2) using the associated handle. 2642 <P> 2643 The event creation requires non-logical copying of the goal. 2644 As a result, if the goal contains variables, they lose their identity 2645 and are replaced with fresh ones. 2646 <P> 2647 The intended use of such events are for localised event handling 2648 or when it is necessary to pass ground parameters to the event goal, 2649 i.e. when the use of a global event handler is unnecessary or does not suffice. 2650 <P> 2651 It should be noted that the event handle is the only way to uniquely 2652 identify a given event. E.g. if an event has been scheduled as an 2653 after-event (using event_after/3 or events_after/2), it can only be 2654 cancelled by invoking cancel_after_event/2 with the correct handle. 2655 "), 2656 amode:(event_create(+,-) is det), 2657 args:["Goal":"An arbitrary goal", "EventHandle":"A free variable"], 2658 exceptions:[4: "Goal is not instantiated", 2659 5 : "Goal is not a valid goal", 2660 5 : "EventHandle is not a free variable"], 2661 eg:"\ 2662 ?- event_create(writeln('Goodbye cruel world!'), Event), 2663 writeln('Hello world!'), 2664 event(Event). 2665 Hello world! 2666 Goodbye cruel world! 2667 Event = 'EVENT'(16'503f0238) 2668 Yes (0.00s cpu) 2669 2670 ?- event_create(writeln('e1'), E1Event), 2671 event_create(writeln('e2'), E2Event), 2672 events_after([E1Event-every(0.2), E2Event-0.5]), 2673 repeat, fail. 2674 e1 2675 e1 2676 e2 2677 e1 2678 e1 2679 ^C 2680 interruption: type a, b, c, e, or h for help : ? e1 2681 abort 2682 Aborting execution ... 2683 ", 2684 see_also:[event_create/3] 2685 ]). 2686 2687 2688:- comment(event_retrieve / 2, [ 2689 summary:"Given the handle with which an event is associated, retrieve the event goal.", 2690 desc:html("\ 2691 The goal associated with an event handle, created using event_create / 3, is 2692 retrieved using this predicate. 2693 <P> 2694 Like event creation, retrieval of the goal produces a copy of the 2695 goal. As a result, if the goal contains variables, they lose their identity 2696 and are replaced with fresh ones. 2697 <P> 2698 If the event was disabled, the goal 'true' is retrieved instead of the 2699 original goal. 2700 "), 2701 amode:(event_retrieve(+,-) is det), 2702 args:["EventHandle":"An event handle", "Goal":"A free variable or goal to unify"], 2703 exceptions:[4: "EventHandle is un-instantiated", 2704 5 : "EventHandle is not a handle"], 2705 eg:"\ 2706 ?- event_create(writeln('Hello world!'), [], Event), event_retrieve(Event, EventGoal). 2707 2708 Event = 'EVENT'(16'50421bd0) 2709 EventGoal = writeln('Hello world!') 2710 Yes (0.00s cpu) 2711 ", 2712 see_also:[event_retrieve/3] 2713 ]). 2714 2715 2716:- comment(lock / 1, [ 2717 summary:"Locks the access to the module Module. 2718 2719", 2720 amode:(lock(+) is det), 2721 desc:html(" Used to forbid the access to the given module when not using its 2722 interface. 2723 2724<P> 2725 It is impossible to unlock a module locked with lock/1. However, a 2726 module locked using lock/2, can still be unlocked with unlock/2. 2727 2728<P> 2729 An error is raised (error 82) when trying to lock a locked module. 2730 2731<P> 2732"), 2733 args:["Module" : "Atom."], 2734 exceptions:[4 : "Module is not instantiated.", 5 : "Module is instantiated, but not to an atom.", 80 : "Module is not a module.", 82 : "Trying to access a locked module Module."], 2735 eg:" 2736Success: 2737 [eclipse]: [user]. 2738 :- module(m). 2739 :- export p/0. 2740 p :- writeln(hello). 2741 user compiled 60 bytes in 0.00 seconds 2742 yes. 2743 [eclipse]: lock(m). 2744 yes. 2745 [eclipse]: module(m). 2746 trying to access a locked module in module(m) 2747 [eclipse]: import p/0 from m. 2748 yes. 2749 [eclipse]: call(p) @ m. 2750 trying to access a locked module in p 2751 [eclipse]: p. 2752 hello 2753 yes. 2754Error: 2755 lock(M). (Error 4). 2756 lock(1). (Error 5). 2757 lock(not_a_module). (Error 80). 2758 lock(m), call(p) @ m. (Error 82). 2759 2760 2761 2762", 2763 see_also:[lock/0, lock_pass/1, lock / 2, unlock / 2, get_module_info/3]]). 2764 2765:- comment(lock / 2, [ 2766 summary:"Locks the access to the module Module, but allow unlocking with the 2767password Password 2768 2769", 2770 amode:(lock(+,+) is det), 2771 desc:html(" Used to forbid the access to the given module when not using its 2772 interface. 2773 2774<P> 2775 The module can later be unlocked by calling unlock(Module, Password). 2776 2777<P> 2778 An error is raised (error 82) when trying to re-lock a locked module. 2779 It must be unlocked first. 2780 2781<P> 2782"), 2783 args:["Module" : "Atom.", "Password" : "String."], 2784 exceptions:[4 : "Module or Password is/are not instantiated.", 5 : "Module is instantiated, but not to an atom or Password is instantiated but not to a string.", 80 : "Module is not a module.", 82 : "Trying to access a locked module Module."], 2785 eg:" 2786Success: 2787 [eclipse]: [user]. 2788 :- module(m). 2789 :- export p/0. 2790 p :- writeln(hello). 2791 user compiled 60 bytes in 0.00 seconds 2792 yes. 2793 [eclipse]: lock(m, \"pass\"). 2794 yes. 2795 [eclipse]: module(m). 2796 trying to access a locked module in module(m) 2797 [eclipse]: import p/0 from m. 2798 yes. 2799 [eclipse]: p. 2800 hello 2801 yes. 2802 [eclipse]: call(p) @ m. 2803 trying to access a locked module in p 2804 [eclipse]: unlock(m, \"pass\"). 2805 yes. 2806 [eclipse]: call(p) @ m. 2807 hello 2808 yes. 2809 2810Error: 2811 lock(M, \"pass\"). (Error 4). 2812 lock(m, Pass). (Error 4). 2813 lock(1, \"pass\"). (Error 5). 2814 lock(not_a_module, \"pass\"). (Error 80). 2815 lock(m, \"pass\"), call(p) @ m. (Error 82). 2816 lock(m, \"pass\"), lock(m, \"new_pass\"). (Error 82). 2817 2818 2819 2820", 2821 see_also:[lock/0, lock_pass/1, lock / 1, unlock / 2, get_module_info/3]]). 2822 2823 2824 2825:- comment(tool / 1, [ 2826 summary:"Declares PredSpec as a tool interface procedure. 2827 2828", 2829 amode:(tool(++) is det), 2830 desc:html(" Informs the system that the (may be not yet visible) procedure PredSpec 2831 is a tool interface procedure. Normally, tool(PredSpecI, PredSpecB) is 2832 used to define a tool interface procedure and declare its body. 2833 However, if PredSpecI is not yet declared as a tool and if the system 2834 has already compiled some calls to it, the tool/2 declaration will cause 2835 an error since the system cannot provide the caller's home module for 2836 calls which are already compiled. 2837 2838<P> 2839 Therefore, when there are modules which are compiled before the tool/2 2840 declaration but which call PredSpecI, tool/1 should be used before the 2841 first call to inform the system that this is a tool interface procedure. 2842 2843<P> 2844"), 2845 args:["PredSpec" : "Expression of the form Atom/Integer."], 2846 exceptions:[4 : "PredSpec is not instantiated.", 5 : "PredSpec is instantiated, but not to an expression of the form Atom/Integer.", 62 : "A call to PredSpec has already been compiled before the tool declaration (``inconsistent procedure redefinition'')."], 2847 eg:" 2848Success: 2849 [eclipse]: tool(list_name/1). % declare as tool 2850 % procedure before 2851 yes. % compiling calls to it. 2852 [eclipse]: [user]. 2853 p :- list_name(p). 2854 user compiled 52 bytes in 0.00 seconds 2855 yes. 2856 [eclipse]: tool_body(current_predicate/1,P,M), 2857 (import P from M). 2858 P = current_predicate_body / 2 2859 M = sepia_kernel 2860 yes. 2861 [eclipse]: tool(list_name/1,list_name_body/2). 2862 yes. 2863 [eclipse]: [user]. 2864 :- export list_name/1. 2865 list_name_body(Name, Module) :- 2866 current_predicate_body(Name/A, Module), 2867 writeln(Name/A), 2868 fail. 2869 list_name_body(_, _). 2870 user compiled 260 bytes in 0.03 seconds 2871 yes. 2872 [eclipse]: module(m). 2873 [m]: [user]. 2874 p(a,b,c,d,e). 2875 user compiled 84 bytes in 0.00 seconds 2876 yes. 2877 [m]: import list_name/1 from eclipse. 2878 yes. 2879 [m]: list_name(p). 2880 p / 5 2881 yes. 2882 [m]: module(eclipse). 2883 [eclipse]: list_name(p). 2884 p / 0 2885 yes. 2886 2887Error: 2888 tool(L). (Error 4). 2889 tool(list_name). (Error 5). 2890 tool(list_name/n). (Error 5). 2891 2892 [eclipse]: [user]. 2893 p :- t. % call compiled before tool declaration 2894 user compiled 32 bytes in 0.00 seconds 2895 yes. 2896 [eclipse]: tool(t/0). (Error 62). 2897 2898 2899 2900", 2901 see_also:[tool / 2, tool_body / 3]]). 2902 2903 2904:- comment(retract_all / 1, [ 2905 summary:"Removes from the database all clauses whose heads match Head", 2906 amode:(retract_all(+) is det), 2907 desc:html("An obsolete synonym for retractall/1."), 2908 args:["Head" : "Atom, variable or compound term."], 2909 exceptions:[4 : "Head is not instantiated", 5 : "Head is not a callable term", 63 : "Procedure is not dynamic", 70 : "Procedure is undefined"], 2910 see_also:[retractall / 1]]). 2911 2912 2913:- comment(flatten_array / 2, [ 2914 summary:"Returns a flat list of the elements of a multi-dimensional array.", 2915 amode:(flatten_array(+,-) is det), 2916 desc:html("\ 2917 List is unified with a flat list of the elements of the array Array. The 2918 elements are returned in the same order as they would be encountered in a 2919 depth-first left-to-right traversal of the array structure. 2920"), 2921 args:[ 2922 "Array" : "Array.", 2923 "List" : "List of terms."], 2924 exceptions:[ 2925 4 : "Array is a variable.", 2926 5 : "Array is not an array." 2927 ], 2928 eg:" 2929?- flatten_array([]([](a,b,c),[](d,e,f)), List). 2930List = [a, b, c, d, e, f] 2931yes. 2932?- flatten_array([](a,b,c), List). 2933List = [a, b, c] 2934yes. 2935?- flatten_array([](a(b),[c,d],[]), List). 2936List = [a(b), [c, d], []] 2937yes. 2938?- flatten_array(Array, List). 2939instantiation fault in flatten_array(Array, List) 2940Abort 2941?- flatten_array([a,b,c], List). 2942type error in flatten_array([a,b,c], List) 2943Abort 2944", 2945 see_also:[dim / 2, subscript / 3, flatten / 2]]). 2946 2947 2948:- comment(select / 3, [ 2949 summary:"Obsolete synonym for stream_select/3", 2950 amode:(select(++,+,-) is det), 2951 args:["StreamList" : "A list of atoms or integers.", 2952 "Timeout" : "A number or an atom.", 2953 "ReadyStreams" : "A term unifiable with a list of integers and atoms."], 2954 see_also:[stream_select/3]]). 2955 2956:- comment(pipe / 2, [ 2957 summary:"Creates a pipe and two streams StreamIn and StreamOut to its read and write ends", 2958 2959 amode:(pipe(-,-) is det), 2960 amode:(pipe(+,+) is det), 2961 desc:html(" Opens a pipe, i.e. two streams, StreamIn for for reading and StreamOut 2962 for writing, which are connected together. This can be used, for 2963 example, to temporarily store data instead of writing it to a file. 2964 2965<P> 2966 Prolog data Data may be written using write( StreamOut,Data). Note that 2967 in order to read data using read/1,2, it must have been written in 2968 Prolog term format (i.e. ended with a period and a blank space 2969 character). Before reading is possible the output must be flushed with 2970 the call flush(StreamOut). 2971 2972<P> 2973 StreamIn and StreamOut can be symbolic stream names (atom) or variable, 2974 in which case they will get instantiated to stream handles. 2975 2976<P> 2977 Each stream can also be specified as sigio(Stream) (BSD systems only). 2978 In this case a pipe is set up and in addition it is instructed to send 2979 the signal io each time new data appears in it. In this way it is 2980 possible to set up an interrupt handler that reads the data from the 2981 pipe and behaves as a lightweight consumer process. 2982 2983<P> 2984 Note that when StreamIn is closed, writing to StreamOut will cause 2985 signal 13. 2986 2987<P> 2988"), 2989 args:["StreamIn" : "Atom or variable.", "StreamOut" : "Atom or variable."], 2990 exceptions:[5 : "Either StreamIn or StreamOut is instantiated, but not to an atom or a sigio structure.", 193 : "StreamIn or StreamOut have wrong mode or are equal."], 2991 eg:" 2992Success: 2993 pipe(a,b). 2994 2995 [eclipse]: pipe(in, out), printf(out, \"a. %b\", []), read(in, A). 2996 2997 A = a 2998 yes. 2999Error: 3000 pipe(0,1). (Error 5). 3001 pipe(26.9,M). (Error 5). 3002 pipe(output, X). (Error 193). 3003 pipe(a, a). (Error 193). 3004 3005 3006 3007", 3008 see_also:[open / 3, open / 4, close / 1, get_stream_info / 3, stream_select / 3]]). 3009 3010:- comment(number_sort / 4, [ 3011 summary:"Succeeds if Sorted is the numerically sorted list 3012 version of Random. The sort is done according to the Key and 3013 Order specifications. 3014 3015", 3016 amode:(number_sort(+,+,+,-) is det), 3017 desc:html("Deprecated, use sort/4! 3018<P> 3019 Sorts the list Random according to the Key and Order specifications, 3020 and unifies Sorted with the result. The sort is stable, i.e. the 3021 order of elements with equal keys is preserved. 3022 3023<P> 3024 If Random is not a list of compound terms, use Key = 0. The list 3025 elements must be numerical terms. 3026 3027<P> 3028 If Random is a list of compound terms, then the sort will be according 3029 to the Keyth argument of the list elements. The Keyth argument of each 3030 list element must be a numeric term. 3031 3032<P> 3033 In all cases, Order specifies whether the list is sorted into ascending 3034 (<, =<) or descending (>, >=) order and whether duplicates are to be 3035 retained (=<, >=) or eliminated (<, >). The way to remember the Order 3036 argument is that it is the relation which holds between adjacent 3037 elements in the result. 3038 3039<P> 3040 The sort is done according to numerical ordering as opposed to 3041 sort/4 which uses the standard ordering of terms. See compare/3 for 3042 this standard ordering. In particular for numeric terms of 3043 different type, e.g. integers and floats, the numerical and 3044 standard orderings differ: 1 < 2.0 but 2.0 @< 1. Additionally 3045 the ordering of bounded reals differs. While the standard ordering 3046 treats a bounded real as a compound term and orders them by lower 3047 bound and then upper bound, numerical ordering treats them as true 3048 intervals. As a consequence the order of overlapping intervals is 3049 undefined: 1.0__1.1 @< 1.0__1.2 while no numerical order is 3050 defined. In such cases an arithmetic exception is thrown. This can 3051 have unexpected consequences: care must be taken when sorting a 3052 list containing both rationals and bounded reals. While integers 3053 and floats are converted to zero-width intervals for the purposes 3054 of comparison, rationals are converted to small intervals 3055 guaranteed to contain the rational, e.g X is breal(1_1) gives 3056 X=0.99999999999999989__1.0000000000000002 and thus no order is 3057 defined between 1_1 and 1.0__1.0. 3058 3059<P> 3060"), 3061 args:["Key" : "A non-negative integer, or a list of positive integers.", "Order" : "One of the atoms <, =<, > or >=.", "Random" : "List.", "Sorted" : "List or variable."], 3062 exceptions:[4: "One of List1 and List2 has an element whose Keyth argument is a variable", 5: "Key is greater than 0, and one of List1 and List2 has an element whose Keyth argument is a non-numeric term", 5 : "Key is greater than 0, and one of List1 and List2 does not have all elements compound terms.", 5 : "Key is not an integer or a list of integers.", 6 : "One of the compound terms in List1 or List2 has not got as many as Key arguments.", 20: "One of List1 and List2 has elements whose numerical order is undefined."], 3063 eg:" 3064Success: 3065 number_sort(0,<,[3,1,6,7,2],S). (gives S=[1,2,3,6,7]). 3066 number_sort(0,=<,[1,1.0,1_1,3,2,3,4,1],S). 3067 (gives S=[1,1.0,1_1,1,2,3,3,4]). 3068 number_sort(0,=<,[1,1.0,1.0__1.0,3,2,3,4,1],S). 3069 (gives S=[1,1.0,1.0__1.0,1,2,3,3,4]). 3070 number_sort(2,<,[f(a,3),h(b,1)],S). (gives S=[h(2,1),f(1,3)]). 3071 number_sort([2,1],=<,[f(3,a(2)),f(1,a(1)),f(0,a(3)),f(1,a(4))],S). 3072 (gives S=[f(1,a(1)),f(3,a(2)),f(0,a(3)),f(1,a(4))]). 3073 3074Fail: 3075 number_sort(0,<,[2,1,3,4],[2,1,3,4]). 3076 3077Error: 3078 number_sort(0,>,[1,3,N],S). (Error 4). 3079 number_sort(0,>,[q,1,3,a,e],S). (Error 5). 3080 number_sort(1,<,[f(1),f(3),5],S). (Error 5). 3081 number_sort(1.0,<,[f(1),f(3),f(5)],S). (Error 5). 3082 number_sort(1,<,[f(a,3),h(b,1)],S). (Error 5). 3083 number_sort(2,<,[f(1,2),g(3,1),f(5)],S). (Error 6). 3084 number_sort(0,<,[1,0.9__1.1],S). (Error 20). 3085 number_sort(0,=<,[1_1,1.0__1.0],S). (Error 20). 3086", 3087 see_also:[compare / 3, number_sort / 2, sort / 2, sort / 4]]). 3088 3089:- comment(number_merge / 5, [ 3090 summary:"Succeeds if List3 is a merged list of List1 and List2. If both lists are 3091sorted, List3 will be sorted. The sort is done according to the Key and 3092Order specifications. 3093 3094", 3095 amode:(number_merge(+,+,+,+,-) is det), 3096 desc:html("Deprecated, use merge/5! 3097<P> 3098 Used to merge the sorted lists List1 and List2 to give the sorted list 3099 List3. 3100 3101<P> 3102 If List1 and List2 are not lists of compound terms, use Key = 0. 3103 3104<P> 3105 If List1 and List2 are lists of compound terms, then the sort will be 3106 according to the Keyth argument of the lists' elements. The Keyth 3107 argument of the list elements must be a numeric term. 3108 3109<P> 3110 For two lists [e1,e2,e3] and [f1,f2,f3], e1 is compared to f1. The 3111 resulting element (dictated by Key, Order and numerical ordering, 3112 with ties being resolved in favour of the element from List1) 3113 is put into List3, and the process continued with the remaining input 3114 lists. This process continues until both lists are exhausted. 3115 3116<P> 3117 In particular, this will merge two sorted lists into a sorted list. The 3118 merge is stable, i.e. the order of elements with equal keys is preserved. 3119 If List1 and List2 contains elements with identical keys, List1's elements 3120 will occur first in List3. 3121 3122<P> 3123 In all cases where List1 and List2 are sorted, Order specifies whether 3124 the lists are sorted into ascending (<, =<) or descending (>, >=) order 3125 and whether duplicates are to be retained (=<, >=) or eliminated (<, >). 3126 The way to remember the Order argument is that it is the relation which 3127 holds between adjacent elements in the result. 3128 3129<P> 3130 The sort is done according to numerical ordering of terms as opposed to 3131 merge/5 which uses the standard ordering of terms. See 3132 number_sort/4 for a discussion of the differences between numerical 3133 and standard ordering of numeric types. 3134 3135<P> 3136"), 3137 args:["Key" : "A non-negative integer, or a list of positive integers.", "Order" : "One of the atoms =<, >=, < or >.", "List1" : "List.", "List2" : "List.", "List3" : "List or variable."], 3138 exceptions:[5 : "Key is greater than 0, and one of List1 and List2 does not have all elements compound terms.", 5 : "Key is not an integer or a list of integers.", 6 : "One of the compound terms in List1 or List2 has not got as many as Key arguments."], 3139 eg:" 3140Success: 3141 number_merge(0,<,[2,4,6],[1,3,5],L). 3142 (gives L=[1,2,3,4,5,6]). 3143 number_merge(1,>,[f(8),f(6)],[f(4),f(1)],L). 3144 (gives L=[f(8),f(6),f(4),f(1)]). 3145 number_merge(2,<,[f(2,1),f(6,4)],[f(6,3),f(8,6)],L). 3146 (gives L=[f(2,1),f(6,3),f(6,4),f(8,6)]). 3147 number_merge(2,<,[q(2,1),f(6,4)],[a(6,3),i(8,6)],L). 3148 (gives L=[q(2,1),a(6,3),f(6,4),i(8,6)]). 3149 number_merge(0,=<,[1,2],[3,4,4,5],L). 3150 (gives L=[1,2,3,4,4,5]). 3151 number_merge([2,1], =<, [f(1,a(1)), f(0,a(3))], [f(3,a(2)), f(1,a(4))], L). 3152 (gives L=[f(1,a(1)), f(3,a(2)), f(0,a(3)), f(1,a(4))]). 3153Fail: 3154 number_merge(0,<,[2,4,6],[1,3,5],[1,2,3,4,5]). 3155Error: 3156 number_merge(0,>,[1],[Q,2],L). (Error 4). 3157 number_merge(1,<,[f(1,2),f],[f(3,4),h(1,2)],L). (Error 5). 3158 number_merge(0.0,<,[f(1)],[f(2)],L). (Error 5). 3159 number_merge(0,<,[f(1),f(7)],[f(8),f(10)],L). (Error 5). 3160 number_merge(0,>,[1,e,q],[2],L). (Error 5). 3161 number_merge(2,<,[f(1,2)],[f(8)],L). (Error 6). 3162 3163 3164 3165", 3166 see_also:[merge / 3, merge / 5, number_merge / 3]]). 3167