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, "Debugging"). 24:- comment(summary, "Built-ins and command related to debugging"). 25:- comment(categories, ["Built-In Predicates","Development Tools"]). 26 27:- tool((spy) / 1). 28:- tool((nospy) / 1). 29:- tool(debug / 1). 30:- tool(debugging / 0). 31:- tool(trace / 1). 32:- tool(trace_call_port / 3). 33:- tool(trace_point_port / 3). 34:- tool((skipped) / 1). 35:- tool((traceable) / 1). 36:- tool((unskipped) / 1). 37:- tool((untraceable) / 1). 38:- tool(spy_term / 2). 39:- tool(spy_var / 1). 40:- tool(kill_display_matrix / 1). 41:- tool(make_display_matrix / 2). 42:- tool(make_display_matrix / 5). 43 44:- comment(nodebug / 0, [ 45 summary:"Switch the debugger off for subsequent top-level queries. 46 47", 48 amode:(nodebug is det), 49 desc:html(" Used to switch tracing mode off (the default). This disables printing 50 of any trace information. A synonym for notrace/0. 51 52<P> 53"), 54 args:[], 55 eg:" 56Success: 57 [eclipse]: [user]. 58 w(X) :- writeln(X). 59 user compiled 44 bytes in 0.00 seconds 60 yes. 61 [eclipse]: trace. 62 yes. 63 Debugger switched on - creep mode 64 [eclipse]: w(X = 2). 65 (1) 0 CALL w(_g54 = 2) (dbg)?- creep % type c 66 B (2) 1 CALL writeln(_g54 = 2) (dbg)?- creep 67 _g54 = 2 68 B (2) 1 EXIT writeln(_g54 = 2) (dbg)?- creep 69 (1) 0 EXIT w(_g54 = 2) (dbg)?- creep 70 X = _g54 71 yes. 72 [eclipse]: nodebug. 73 Debugger switched off 74 yes. 75 [eclipse]: w(X = 2). 76 _g54 = 2 77 X = _g54 78 yes. 79 80 81 82", 83 see_also:[notrace / 0, trace / 0, trace / 1, debug / 0, debug / 1]]). 84 85:- comment((nospy) / 1, [ 86 summary:"All spypoints or breakpoints are removed from all the procedures given by 87SpecList. If SpecList is a variable, remove all spypoints. 88 89", 90 template:"nospy ?Speclist", 91 amode:(nospy(?) is det), 92 desc:html(" Removes spypoints or breakpoints from all procedures given by SpecList. 93 94<P> 95 If SpecList is of the form Name or Module:Name, where Name is an atom, then 96 spypoints are removed from procedures from module Moudle (if given) with 97 name Name and of any arity. 98 99<P> 100 If SpecList is of the form File:Line, where File is a file name and Line is 101 an integer, the the closest matching breakpoint to line Line in the file 102 File is removed. If Line is a variable, then all breakpoints in file File 103 are removed. 104 105<P> 106 If SpecList is a variable, all spypoints of visible procedures are 107 removed. 108 109<P> 110 Note that spypoints can also be removed with set_flag(Proc, spy, off). 111 112<P> 113"), 114 args:["SpecList" : "Sequence of expressions of the form Atom/Integer, Module:Atom/Integer, Module:Atom, Atom, File:Line or Variable."], 115 exceptions:[5 : "SpecList is not in the correct form.", 60 : "SpecList is an undefined procedure."], 116 eg:" 117 118Success: 119 [eclipse 1]: [user]. 120 q. 121 p :- q, writeln(hi). 122 tty compiled 132 bytes in 0.00 seconds 123 124 Yes (0.15s cpu) 125 [eclipse 2]: spy q. 126 spypoint added to q/0. 127 Debugger switched on - leap mode 128 129 Yes (0.00s cpu) 130 [eclipse 3]: p. 131 132 +(2) 2 CALL q %> leap 133 +(2) 2 EXIT q %> leap 134 hi 135 136 Yes (0.00s cpu) 137 [eclipse 4]: nospy q. 138 spypoint removed from q/0. 139 140 Yes (0.00s cpu) 141 [eclipse 5]: p. 142 hi 143 144 Yes (0.00s cpu) 145 [eclipse 6]: 146 147Error: 148 nospy(\"l\"). (Error 5). 149 150 151 152", 153 see_also:[(spy) / 1, get_flag / 3, set_flag / 3]]). 154 155:- comment(notrace / 0, [ 156 summary:"Switch the debugger off for subsequent top-level queries. 157 158", 159 amode:(notrace is det), 160 desc:html(" Used to switch tracing mode off (the default). This disables printing 161 of any trace information. 162 163<P> 164"), 165 args:[], 166 eg:" 167Success: 168 [eclipse]: [user]. 169 w(X) :- writeln(X). 170 user compiled 44 bytes in 0.00 seconds 171 yes. 172 [eclipse]: trace. 173 Debugger switched on - creep mode 174 yes. 175 [eclipse]: w(X = 2). 176 (1) 0 CALL w(_g54 = 2) (dbg)?- creep % type c 177 B (2) 1 CALL writeln(_g54 = 2) (dbg)?- creep 178 _g54 = 2 179 B (2) 1 EXIT writeln(_g54 = 2) (dbg)?- creep 180 (1) 0 EXIT w(_g54 = 2) (dbg)?- creep 181 X = _g54 182 yes. 183 [eclipse]: notrace. 184 Debugger switched off 185 yes. 186 [eclipse]: w(X = 2). 187 _g54 = 2 188 X = _g54 189 yes. 190 191 192 193", 194 see_also:[nodebug / 0, trace / 0, trace / 1, debug / 0, debug / 1]]). 195 196:- comment(set_leash / 2, [ 197 summary:"Currently not supported. 198 199", 200 amode:(set_leash(?,+) is det), 201 desc:html(" Sets the port specified by Port to the leash mode Leash. 202 Currently not supported. 203 204<P> 205"), 206 args:["Ports" : "Atom, list of atoms, or variable.", "Leash" : "Atom."], 207 exceptions:[4 : "Leash is not instantiated.", 5 : "Ports is instantiated, but not to an atom or a list of atoms.", 5 : "Ports is instantiated to an atom or list of atoms, but the atoms are not all valid ports.", 5 : "Leash is instantiated, but not to an atom.", 5 : "Ports is instantiated to an atom, but not to one of the leashing modes."], 208 eg:" 209 210 211", 212 see_also:[get_leash / 2]]). 213 214:- comment((skipped) / 1, [ 215 summary:"Declares all the procedures given in SpecList as skipped. 216 217", 218 template:"skipped +SpecList", 219 amode:(skipped(++) is det), 220 desc:html(" Sets all the procedures given by SpecList in skipped mode. Marking a 221 predicate as skipped will prevent any information about its subgoals 222 being displayed by the debugger. 223 224<P> 225 The procedures are all of the form name/arity, or else of the form name, 226 in which case all procedures with name name are skipped. 227 228<P> 229 Note that skipped/1 is superseded by the predicate call set_flag(Proc, 230 skip, on), which declares the procedure Proc as skipped. 231 232<P> 233"), 234 args:["SpecList" : "Sequence of expressions of the form Atom/Integer."], 235 exceptions:[4 : "SpecList is not instantiated.", 5 : "SpecList is instantiated, but is not of the form atom or Atom/Integer.", 60 : "SpecList is not a defined procedure."], 236 eg:" 237Success: 238 [eclipse]: [user], skipped p/0. 239 q. p :- q. 240 user compiled 60 bytes in 0.02 seconds 241 yes. 242 [eclipse]: trace. 243 Debugger switched on - creep mode 244 yes. 245 [eclipse]: p. 246 S (1) 0 CALL p (dbg)?- creep 247 S (1) 0 EXIT p (dbg)?- creep % information on 248 yes. % q not printed. 249Error: 250 skipped Proc/1. (Error 4). 251 skipped write(Term)/1. (Error 5). 252 skipped do. (Error 5). 253 skipped n/1. (Error 60). 254 255 256 257", 258 see_also:[(unskipped) / 1, get_flag / 3, set_flag / 3]]). 259 260:- comment((spy) / 1, [ 261 summary:"Sets a spypoint for the procedure(s) in SpecList. 262 263", 264 template:"spy +SpecList", 265 amode:(spy(++) is det), 266 desc:html(" 267 This predicate sets spypoints on all the procedures given by SpecList, 268 or sets a breakpoint on a call in a specific source line. 269<P> 270 For setting spypoints, the procedure(s) are all of the form name/arity, 271 or else of the form name, in which case all procedures with name name 272 and any arity have spy points set. 273<P> 274 For setting a breakpoint, SpecList should be of the form File:Line, where 275 File is the name of a source file (atom/string) whose code is already 276 loaded into ECLiPSe, and Line is an integer that specifies a line number 277 in the file. Breakpoints can only be set in procedures that have been 278 compiled in debug mode. A breakpoint will be added to the subgoal call 279 that most closely matches the line number Line, i.e. the subgoal call 280 is either on, or close to, line Line in File. 281<P> 282 If not already debugging, the trace mode is switched on and set to leap. 283<P> 284 When tracing, a leap command to the debugger will cause execution to 285 continue until it reaches a spied predicate. Setting a spy-point on a 286 non-existing procedure results in an error. 287<P> 288 Note that spypoints can also be set using set_flag(Proc, spy, on). 289<P> 290"), 291 args:["SpecList" : "Sequence of expressions of the form Atom/Integer, Module:Atom/Integer, Atom or File:Line"], 292 exceptions:[4 : "SpecList is not instantiated.", 293 5 : "SpecList is not of the correct form", 294 6 : "SpecList in the form File:Line did not correspond to a source file or breakpoint", 295 60 : "SpecList contains an undefined procedure."], 296 297 eg:" 298Success: 299 [eclipse]: [user]. 300 lower:-writeln(hi). 301 higher:-lower. 302 user compiled 84 bytes in 0.00 seconds 303 yes. 304 [eclipse]: spy higher,writeln. 305 spypoint added to higher / 0. 306 spypoint added to writeln / 1. 307 spypoint added to writeln / 2. 308 yes. 309 [eclipse]: higher. 310 +(1) 0 CALL higher (dbg)?- leap 311 B+(3) 2 CALL writeln(hi) (dbg)?- leap 312 hi 313 B+(3) 2 EXIT writeln(hi) (dbg)?- leap 314 +(1) 0 EXIT higher (dbg)?- leap 315 yes. 316Error: 317 spy(I). (Error 4). 318 spy(\"l\"). (Error 5). 319 spy(foo). (Error 60). 320 321 322 323", 324 see_also:[(nospy) / 1, get_flag / 3, set_flag / 3]]). 325 326:- comment((unskipped) / 1, [ 327 summary:"Sets the procedures specified in SpecList to be unskipped or not skipped. 328 329", 330 template:"unskipped +SpecList", 331 amode:(unskipped(++) is det), 332 desc:html(" Undoes the effect of a call to skipped/1 on the specified procedure(s), 333 i.e. its subgoals will now be traced. 334 335<P> 336 The expressions in SpecList are all of the form name/arity. 337 338<P> 339 Note that unskipped/1 is superseded by the predicate set_flag(Proc, 340 skip, off), which sets the procedure Proc to be unskipped. 341 342<P> 343"), 344 args:["SpecList" : "Sequence of expressions of the form Atom/Integer."], 345 exceptions:[4 : "SpecList is not instantiated.", 5 : "SpecList is instantiated, but not of the form atom or Atom/Integer.", 60 : "SpecList contains an undefined procedure."], 346 eg:" 347Success: 348 [eclipse]: [user], skipped p/0. 349 q. 350 p :- q. 351 user compiled 60 bytes in 0.00 seconds 352 yes. 353 [eclipse]: trace. 354 Debugger switched on - creep mode 355 yes. 356 [eclipse]: p. 357 S (1) 0 CALL p (dbg)?- creep 358 S (1) 0 EXIT p (dbg)?- creep 359 yes. 360 [eclipse]: unskipped p/0. 361 yes. 362 [eclipse]: p. 363 (1) 0 CALL p (dbg)?- creep 364 (2) 1 CALL q (dbg)?- creep 365 (2) 1 EXIT q (dbg)?- creep 366 (1) 0 EXIT p (dbg)?- creep 367 yes. 368 369Error: 370 unskipped Proc/1. (Error 4). 371 unskipped write(Term)/1. (Error 5). 372 unskipped do. (Error 5). 373 unskipped n/1. (Error 60). 374 375 376 377", 378 see_also:[(skipped) / 1]]). 379 380:- comment((untraceable) / 1, [ 381 summary:"Declares the procedure(s) in SpecList to be untraceable. 382 383", 384 template:"untraceable +SpecList", 385 amode:(untraceable(++) is det), 386 desc:html(" Sets all the procedures given by SpecList untraceable. Marking a 387 predicate as untraceable will prevent any information about it being 388 displayed. The subgoals of this predicate will be shown in their normal 389 way. 390 391<P> 392 Note that untraceable/1 is superseded by the predicate set_flag(Proc, 393 leash, notrace), which declares the procedure Proc to be untraceable. 394 395<P> 396"), 397 args:["SpecList" : "Sequence of expressions of the form name/arity."], 398 exceptions:[4 : "SpecList is not instantiated.", 5 : "SpecList is not of the form Atom/Integer.", 60 : "SpecList is an undefined procedure."], 399 see_also:[get_flag / 3, set_flag / 3, (traceable) / 1]]). 400 401:- comment(spy_term / 2, [ 402 summary:"Create a SPYTERM-port in the debugger and prepare for tracing 403modifications to Term as MODIFY-ports. 404 405", 406 amode:(spy_term(?,++) is det), 407 desc:html(" This predicate allows to trace modifications to variables in Term. 408 409<P> 410 When the debugger is on, this predicate causes a SPYTERM-port 411 to be displayed. In the subsequent execution, any variable 412 modification in Term which satisfies the trigger condition Cond 413 will be shown as a MODIFY-port. The SPYTERM and MODIFY-port have 414 the same unique invocation number, therefore the invocation-skip 415 command (i) can be used to follow the chain of modifications. 416 417<P> 418 The trigger conditions are specified in the same way as in the 419 suspend/3 built-in. 420 421 This feature is implemented using high-priority (1) delayed goals 422 which create the MODIFY-ports. These goals are visible to the 423 user as monitor_term/4 goals among the delayed goals. 424 425<P> 426 CAUTION: Term is interpreted by the debugger as a goal. If Term 427 looks like a call of a visible predicate, this predicate's settings 428 (spy, traceable, etc) are taken into account for the SPYTERM and 429 MODIFY ports as well. In particular, don't use a list for Term, 430 since that looks like the compile-built-in ./2 which is untraceable. 431 432<P> 433"), 434 args:["Term" : "A variable or any term containing variables.", "Cond" : "A trigger condition (as in suspend/3)."], 435 exceptions:[6 : "Not a valid trigger condition."], 436 eg:" 437[eclipse 1]: lib(fd). 438yes. 439 440[eclipse 1]: trace. 441Debugger switched on - creep mode 442 443[eclipse 3]: [X, Y] :: 1..9, 444\t spy_term(v(X,Y), v(X,Y)->any), 445\t X #> Y, Y #> X. 446 (1) 1 CALL [X, Y] :: 1..9 %> creep 447 (1) 1 EXIT [X{[... .. ...]}, Y{[...]}] :: 1..9 %> creep 448 (3) 2 SPYTERM v(X{[1..9]}, Y{[1..9]}) %> jump to invoc: [3]? 449 (3) 3 MODIFY v(X{[2..9]}, Y{[1..8]}) %> jump to invoc: [3]? 450 (3) 3 MODIFY v(X{[2..7]}, Y{[3..8]}) %> jump to invoc: [3]? 451 (3) 4 MODIFY v(X{[4..7]}, Y{[3..6]}) %> jump to invoc: [3]? 452 (3) 4 MODIFY v(X{[4, 5]}, Y{[5, 6]}) %> jump to invoc: [3]? 453 454no (more) solution. 455 456 457 458 459", 460 see_also:[suspend / 3, spy_var / 1, trace_point_port / 3, trace / 1]]). 461 462:- comment(spy_var / 1, [ 463 summary:"Create a SPYTERM-port in the debugger and prepare for tracing 464modifications to Var as MODIFY-ports. 465 466", 467 amode:(spy_var(?) is det), 468 desc:html(" This predicate allows to trace modifications to the variable Var. 469 470<P> 471 When the debugger is on, this predicate causes a SPYTERM-port to 472 be displayed. In the subsequent execution, any variable 473 modification in Var will be shown as a MODIFY-port. The SPYTERM 474 and MODIFY-port have the same unique invocation number, therefore 475 the invocation-skip command (i) can be used to follow the chain of 476 modifications. 477 478<P> 479 This is equivalent to 480 481<P> 482<PRE> 483 spy_term(Var, Var->(constrained of suspend)) 484</PRE> 485 486 This feature is implemented using high-priority (1) delayed goals 487 which create the MODIFY-ports. These goals are visible to the 488 user as monitor_term/4 goals among the delayed goals. 489 490<P> 491"), 492 args:["Var" : "A variable, possibly attributed."], 493 eg:" 494[eclipse 1]: lib(fd). 495yes. 496 497[eclipse 1]: trace. 498Debugger switched on - creep mode 499 500[eclipse 3]: [X, Y] :: 1..9, spy_var(X), X #> Y, Y #> X. 501 (1) 1 CALL [X, Y] :: 1..9 %> creep 502 (1) 1 EXIT [X{[1..9]}, Y{[1..9]}] :: 1..9 %> creep 503 (3) 2 SPYTERM X{[1..9]} %> jump to invoc: [3]? 504 (3) 3 MODIFY X{[2..9]} %> jump to invoc: [3]? 505 (3) 4 MODIFY X{[4..7]} %> jump to invoc: [3]? 506 507no (more) solution. 508 509 510 511 512", 513 see_also:[suspend / 3, spy_term / 2, trace_point_port / 3, trace / 1]]). 514 515 516:- comment(trace_point_port / 3, [ 517 summary:"Create a user-defined debugger port. 518 519", 520 desc:html(" 521 This predicate allows to generate user-defined debugger ports, 522 thus enhancing the debugger's basic box model with application- 523 specific checkpoints. 524<P> 525 When the debugger is on, this predicate causes a trace line to 526 be displayed with Port being the name of the debugger port, 527 invocation number Invoc and Term in the goal position. 528<P> 529 If Invoc is left uninstantiated, it will be instantiated to a 530 unique invocation number by the system, if it is an integer, it 531 will be used. This way, several ports can be made to share the 532 same invocation number, which makes it possible to easily i-skip 533 from one to the other. 534<P> 535"), 536 amode:(trace_point_port(+,+,?) is det), 537 amode:(trace_point_port(+,-,?) is det), 538 args:["Port" : "An atom.", 539 "Invoc" : "An integer or variable.", 540 "Term" : "Any term."], 541 eg:" 542 :- pragma(nodebug). 543 bool(B) :- 544 trace_point_port(try_zero, Invoc, B=0), 545 ( 546 B=0 547 ; 548 trace_point_port(try_one, Invoc, B=1), 549 B=1 550 ). 551 :- untraceable bool/1. 552 553[eclipse 9]: bool(B). 554 (3) 3 TRY_ZERO B = 0 %> creep 555 556B = 0 More? (;) 557 (3) 3 TRY_ONE B = 1 %> creep 558 559B = 1 560yes. 561", 562 see_also:[trace_call_port/3, trace_parent_port/1, trace_exit_port/0, spy_term / 2, spy_var / 1, trace / 1]]). 563 564 565:- comment(trace_call_port / 3, [ 566 summary:"Create a user-defined debugger port (CALL-style). 567 568", 569 desc:html(" 570 This predicate allows to generate a user-defined debugger port, 571 thus enhancing the debugger's basic box model with application- 572 specific checkpoints. In the box model, the execution is viewed as 573 consisting of nested boxes, which are being entered via CALL or 574 REDO ports, and left via EXIT, FAIL or LEAVE ports. 575<P> 576 When the debugger is on, this predicate causes a new box to be entered, 577 i.e. a trace line to be displayed with Port being the name of the port, 578 invocation number Invoc and Term in the goal position. 579<P> 580 It is important to use a corresponding trace_exit_port/0 call after 581 every call to trace_call_port/3, otherwise the debugger's box 582 nesting will get out of sync. Note however, that fail ports for 583 the new box will be generated automatically. 584<P> 585 If Invoc is left uninstantiated, it will be instantiated to a 586 unique invocation number by the system. 587<P> 588"), 589 amode:(trace_call_port(+,+,?) is det), 590 amode:(trace_call_port(+,-,?) is det), 591 args:["Port" : "An atom.", 592 "Invoc" : "An integer or variable.", 593 "Term" : "Any term."], 594 eg:" 595 search(Vars) :- 596 trace_call_port(search_enter, _Invoc, search(Vars)), 597 labeling(Vars), 598 trace_exit_port. 599 600?- length(L, 3), L :: 1..4, search(L). 601 (1) 1 CALL length(L, 3) %> zap to port: [~ call] search_enter 602 (6) 2 SEARCH_ENTER search([_501{[... .. ...]}, _514{[...]}, _527{...}]) %> skip 603 (6) 2 *EXIT search([1, 1, 1]) %> skip 604", 605 see_also:[trace_point_port/3, trace_parent_port/1, trace_exit_port/0, spy_term / 2, spy_var / 1, trace / 1]]). 606 607 608:- comment(trace_exit_port / 0, [ 609 summary:"Create an exit-port for the current procedure box.", 610 desc:html(" 611 This predicate allows to generate a user-defined debugger port, 612 thus enhancing the debugger's basic box model with application- 613 specific checkpoints. In the box model, the execution is viewed as 614 consisting of nested boxes, which are being entered via CALL or 615 REDO ports, and left via EXIT, FAIL or LEAVE ports. 616<P> 617 When the debugger is on, this predicate causes the current innermost 618 box to be exited. This should be a box created previously by the 619 trace_call_port/3 builtin, otherwise the debugger's box 620 nesting will get out of sync. 621<P> 622"), 623 amode:(trace_exit_port is det), 624 eg:" 625 search(Vars) :- 626 trace_call_port(search_enter, _Invoc, search(Vars)), 627 labeling(Vars), 628 trace_exit_port. 629 630?- length(L, 3), L :: 1..4, search(L). 631 (1) 1 CALL length(L, 3) %> zap to port: [~ call] search_enter 632 (6) 2 SEARCH_ENTER search([_501{[... .. ...]}, _514{[...]}, _527{...}]) %> skip 633 (6) 2 *EXIT search([1, 1, 1]) %> skip 634", 635 see_also:[trace_call_port/3, trace_point_port/3, trace_parent_port/1, spy_term / 2, spy_var / 1, trace / 1]]). 636 637 638:- comment(trace_parent_port / 1, [ 639 summary:"Create a user-defined debugger port for the parent box.", 640 desc:html(" 641 This predicate allows to generate a user-defined debugger port, 642 thus enhancing the debugger's basic box model with application- 643 specific checkpoints. In the box model, the execution is viewed as 644 consisting of nested boxes, which are being entered via CALL or 645 REDO ports, and left via EXIT, FAIL or LEAVE ports. 646<P> 647 When the debugger is on, this predicate causes a trace line to 648 be displayed for the current innermost box, with Port being the 649 name of the port, and all other information being the current 650 box's ones. 651<P> 652"), 653 amode:(trace_parent_port(+) is det), 654 args:["Port" : "An atom."], 655 eg:" 656 p :- 657 trace_parent_port(clause1), 658 writeln(hello), 659 fail. 660 p :- 661 trace_parent_port(clause2), 662 writeln(world). 663 664?- p. 665 (1) 1 CALL p %> creep 666 (1) 1 CLAUSE1 p %> creep 667S (2) 2 CALL writeln(hello) %> creep 668hello 669S (2) 2 EXIT writeln(hello) %> creep 670 (3) 2 CALL fail %> creep 671 (3) 2 FAIL fail %> creep 672 (1) 1 NEXT p %> creep 673 (1) 1 CLAUSE2 p %> creep 674S (4) 2 CALL writeln(world) %> creep 675world 676S (4) 2 EXIT writeln(world) %> creep 677 (1) 1 EXIT p %> creep 678 679Yes (0.00s cpu) 680", 681 see_also:[trace_call_port/3, trace_point_port/3, trace_exit_port/0, spy_term / 2, spy_var / 1, trace / 1]]). 682 683 684:- comment(debug / 0, [ 685 summary:"Execute subsequent top-level queries with the debugger on. 686 687", 688 amode:(debug is det), 689 desc:html(" If the debugger is already on, no effect. If not, the debugger 690 will be switched on at the next top-level query. The debugger will 691 stay on until it is switched off with notrace/0. 692 693<P> 694 The debugger will stop at the first traceable port. 695 696<P> 697 This is not actually a predicate but a toplevel-command. 698"), 699 args:[], 700 eg:" 701[eclipse 1]: [user]. 702p :- true, writeln(hello). 703user compiled traceable 68 bytes in 0.00 seconds 704 705Yes (0.01s cpu) 706 707[eclipse 2]: spy writeln/1. 708spypoint added to sepia_kernel:writeln/1. 709Debugger switched on - leap mode 710Yes (0.00s cpu) 711 712[eclipse 3]: trace. 713Debugger switched on - creep mode 714 715[eclipse 4]: p. 716 (1) 1 CALL p %> creep 717S+(2) 2 CALL writeln(hello) %> creep 718hello 719S+(2) 2 EXIT writeln(hello) %> creep 720 (1) 1 EXIT p %> creep 721Yes (0.00s cpu) 722 723[eclipse 5]: debug. 724Debugger switched on - leap mode 725 726[eclipse 9]: p. 727S+(2) 2 CALL writeln(hello) %> creep 728hello 729S+(2) 2 EXIT writeln(hello) %> creep 730 (1) 1 EXIT p %> creep 731Yes (0.00s cpu) 732", 733 see_also:[notrace / 0, trace / 0, trace / 1, debug / 1]]). 734 735:- comment(debug / 1, [ 736 summary:"Execute the goal Goal with the debugger in leap mode. 737 738", 739 amode:debug(+), 740 desc:html(" The goal Goal is called with the debugger in leap mode. 741 debug/1 succeeds or fails depending if Goal succeeds or fails. 742 743<P> 744 This predicate is particularly useful for debugging large programs that 745 would take too much space or time to run completely with the debugger. 746 The debugger is only switched on in leap mode at the call port of Goal 747 and switched off when Goal exits (or fails, leaves,...). 748 749<P> 750 If the debugger was already on before calling debug/1, it has no effect. 751 752<P> 753 An alternative way of turning on the debugger selectively is to 754 set the start_tracing property of a particular predicate using 755 set_flag/3. 756 757<P> 758"), 759 args:["Goal":"Atom or compound term."], 760 resat:"Resatisifable if Goal is resatisfiable", 761 fail_if:"Fails if Goal fails", 762 eg:" 763Success: 764 [eclipse]: [user]. 765 p :- big_goal1, debug(buggy_goal), big_goal2. 766 big_goal1. 767 big_goal2. 768 buggy_goal. 769 user compiled 208 bytes in 0.02 seconds 770 yes. 771 [eclipse]: set_flag(big_goal2/0, spy, on), 772 set_flag(buggy_goal/0, spy, on). 773 yes. 774 [eclipse]: p. 775 Start debugging - leap mode 776 +(1) 0 CALL buggy_goal %> creep 777 +(1) 0 EXIT buggy_goal %> creep 778 Stop debugging. 779 yes. 780 781 782 783", 784 see_also:[debug / 0, notrace / 0, trace / 0, trace / 1, set_flag / 3]]). 785 786:- comment(debugging / 0, [ 787 summary:"Prints summary information about the debugger state", 788 amode:(debugging is det), 789 desc:html(" Prints the information about the tracing mode: whether it is off, 790 in creep or in leap mode. 791 It then lists all procedures with a spypoint set, and then all breakpoints. 792 The information is printed to the log_output stream. 793<P> 794"), 795 args:[], 796 eg:" 797[eclipse 1]: debugging. 798Debugger is switched off 799yes. 800 801[eclipse 2]: trace. 802Debugger switched on - creep mode 803 804[eclipse 3]: trace. 805Debugger switched on - creep mode 806 807[eclipse 4]: spy writeln/1. 808spypoint added to writeln / 1. 809yes. 810 811[eclipse 6]: debugging. 812Debug mode is debug 813writeln/1 is being spied 814yes. 815 816 817 818", 819 see_also:[(spy) / 1, trace / 0, debug / 0, notrace / 0]]). 820 821:- comment(debug_reset / 0, [ 822 summary:"Reset the debugger", 823 amode:(debug_reset is semidet), 824 desc:html(" 825 Reset the debugger. In particular, this includes: 826 <UL> 827 <LI>reset invocation numbers so they start from 0 again 828 <LI>reset all filter conditions 829 <LI>raise the debug-init event (250) at the next trace/1, debug/1 830 or any predicate that has the start_tracing flag set. 831 </UL> 832 Note that debug_reset/0 just sets some parameters, it does not 833 activate the debugger immediately. This only happens when a trace/1, 834 debug/1, or predicate with the start_tracing flag is executed. 835 <P> 836 The debugger cannot be reset while it is active. The predicate will 837 fail in this case. 838"), 839 fail_if:"Debugger is active and cannot be reset at this time", 840 eg:" 841[eclipse]: trace(true), trace(true), debug_reset, trace(true). 842 (1) 1 CALL true %> creep 843 (1) 1 EXIT true %> creep 844 (3) 1 CALL true %> creep 845 (3) 1 EXIT true %> creep 846 (1) 1 CALL true %> creep 847 (1) 1 EXIT true %> creep 848", 849 see_also:[trace / 1, debug / 1]]). 850 851:- comment(get_leash / 2, [ 852 summary:"Currently not supported. 853 854", 855 amode:(get_leash(+,-) is det), 856 amode:(get_leash(-,-) is multi), 857 desc:html(" Unifies Leash with the leashing mode of the port or ports specified by 858 Port. Currently not supported. 859 860<P> 861"), 862 args:["Port" : "Atom or variable.", "Leash" : "Atom or variable."], 863 exceptions:[5 : "Port is instantiated, but not to an atom.", 5 : "Port is instantiated to an atom, but not to one of the valid ports.", 5 : "Leash is instantiated, but not to an atom."], 864 eg:" 865 866 867", 868 see_also:[set_leash / 2, get_flag / 3, set_flag / 3]]). 869 870:- comment(trace / 0, [ 871 summary:"Execute subsequent top-level queries with the debugger on. 872 873", 874 amode:(trace is det), 875 desc:html(" If the debugger is already on, no effect. If not, the debugger 876 will be switched on at the next top-level query. The debugger will 877 stay on until it is switched off with notrace/0. 878 879<P> 880 The debugger will stop at the first traceable port. 881 882<P> 883 This is not actually a predicate but a toplevel-command. 884"), 885 args:[], 886 eg:" 887[eclipse 1]: [user]. 888p :- true, writeln(hello). 889user compiled traceable 68 bytes in 0.00 seconds 890 891yes. 892[eclipse 2]: trace. 893Debugger switched on - creep mode 894[eclipse 3]: p. 895 (1) 1 CALL p %> creep 896S (2) 2 CALL writeln(hello) %> creep 897hello 898S (2) 2 EXIT writeln(hello) %> creep 899 (1) 1 EXIT p %> creep 900 901yes. 902 903 904 905", 906 see_also:[debug / 0, debug / 1, notrace / 0, trace / 1]]). 907 908:- comment(trace / 1, [ 909 summary:"Execute the goal Goal with the debugger in creep mode. 910 911", 912 amode:trace(+), 913 desc:html(" The goal Goal is called with the debugger in creep mode. 914 trace/1 succeeds or fails depending if Goal succeeds or fails. 915 916<P> 917 This predicate is particularly useful for debugging large programs that 918 would take too much space or time to run completely with the debugger. 919 The debugger is only switched on in creep mode at the call port of Goal 920 and switched off when Goal exits (or fails, leaves,...). 921 922<P> 923 If the debugger was already on before calling trace/1, it has 924 no effect. 925 926<P> 927 An alternative way of turning on the debugger selectively is to 928 set the start_tracing property of a particular predicate using 929 set_flag/3. 930 931<P> 932"), 933 args:["Goal":"Atom or compound term."], 934 resat:"Resatisifable if Goal is resatisfiable", 935 fail_if:"Fails if Goal fails", 936 eg:" 937Success: 938 [eclipse]: [user]. 939 p :- big_goal1, trace(buggy_goal), big_goal2. 940 big_goal1. 941 big_goal2. 942 buggy_goal. 943 user compiled 208 bytes in 0.02 seconds 944 yes. 945 [eclipse]: p. 946 % big_goal1/0 is executed without the debugger 947 Start debugging - creep mode 948 (1) 0 CALL buggy_goal %> creep 949 (1) 0 EXIT buggy_goal %> creep 950 Stop debugging. 951 % big_goal2/0 is executed without the debugger 952 yes. 953 954 955 956", 957 see_also:[notrace / 0, trace / 0, debug / 0, debug / 1, set_flag / 3]]). 958 959:- comment((traceable) / 1, [ 960 summary:"Sets the procedures in SpecList to be traceable. 961 962", 963 template:"traceable +SpecList", 964 amode:(traceable(++) is det), 965 desc:html(" Sets the leash mode of all the procedures given by SpecList to stop. 966 967<P> 968 It is superseded by calling set_flag(Proc, leash, stop) 969 970<P> 971"), 972 args:["SpecList" : "Sequence of expressions of the form Atom/Integer."], 973 exceptions:[4 : "SpecList is not instantiated.", 5 : "SpecList is not of the form Atom/Integer.", 60 : "SpecList is an undefined procedure."], 974 see_also:[get_flag / 3, set_flag / 3, (untraceable) / 1]]). 975 976:- comment(kill_display_matrix / 1, [ 977 summary:" Destroys an existing display matrix. 978 979", 980 amode:(kill_display_matrix(+) is det), 981 desc:html("\ 982 Destroys an existing display matrix. The display matrix is removed 983 from being displayed. This command can only kill a display matrix within 984 the `logical scope' of the display matrix, i.e. within the part of the 985 search-tree rooted at the node where the display matrix was created. 986 The display matrix window may persist beyond the logical scope, and in 987 such cases the window can only be killed on the GUI side. Normally, 988 the matrix is removed on backtracking pass its point of creation, but 989 this may not occur due to cuts. 990 991<P> 992 Name is mapped into a string internally, so a name that is a atom or 993 number is the same name as its equivalent string (i.e. 'matrix' and 994 \"matrix\" are the same name). Note that display matrix names are local 995 to a module, so it should be killed in the module in which it was 996 created (perhaps with @/2 wrapper around the call). 997 998<P> 999"), 1000 args:["Name" : "An atomic term."], 1001 exceptions:[5 : "Name is not an atomic term.", 6 : "Name is not an existing display matrix."], 1002 eg:" 1003 kill_display_matrix(queens). 1004 1005 1006 1007", 1008 see_also:[make_display_matrix / 5, make_display_matrix / 2, (@) / 2]]). 1009 1010:- comment(make_display_matrix / 2, [ 1011 summary:" Creates a display matrix of terms that can be monitored with the 1012 graphical ECLiPSe (the predicate will succeed silently in tty ECLiPSe). 1013 1014", 1015 amode:(make_display_matrix(+,+) is det), 1016 desc:html(" Set up a one or two dimensional matrix of terms that can then be 1017 monitored for changes in their values. The terms are either provided in 1018 the form of an array (the nested structure type, compatible with dim/2), 1019 or in the form +List/+Spec, where List is a list of the terms, and Spec 1020 is an integer specifying the number of cells per row of the matrix, 0 1021 means that the matrix is to have only one row (except if the members of 1022 the list are matricies of the same size, in which case a two dimensional 1023 matrix will be created). If List is supplied without a Spec, this is 1024 treated as Spec = 0. Name specifies the name that is associated with 1025 this display matrix, and cannot be used for another display matrix that 1026 is active at the same time in the same module. The name is mapped into a 1027 string internally, so a name that is a atom or number is the same name 1028 as its equivalent string (i.e. 'matrix' and \"matrix\" are the same name). 1029 1030<P> 1031 The terms are monitored by placing a demon suspension on the variables 1032 in each term. When a demon wakes, the new value of the term it is 1033 associated with is sent to the display matrix (and possibly updated, 1034 depending on the interactive settings on the matrix). When the new 1035 value is backtracked, the old value is sent to the display matrix. 1036 This predicate sets default value for how the demon is suspended: it 1037 is suspended with a priority of 1, and in the constrained suspension 1038 list. This should enable it to monitor all changes unless the changes 1039 were also effected by suspensions of priority 1. 1040 1041<P> 1042 The display matrix will be removed on backtracking. However, it will 1043 not be removed if make_display_matrix has been cut. It is possible to 1044 explicitly remove a matrix with kill_display_matrix/1. 1045 1046<P> 1047 Each cell of the display matrix represents one term. The value of the 1048 term is displayed in the cell, and break-points can be set from a pop-up 1049 menu so that execution suspends when an update occurs in a cell. The 1050 term can also be inspected by the inspector. The actual current value of 1051 the term will be examined, which may be different from the value shown 1052 in the cell depending on how often the cell is updated. With breaks, the 1053 changes due to forward execution (further constraining of a variable's 1054 value) and backtracking are shown in different colours. Inspection is 1055 not allowed on a term that has just been backtracked, because the actual 1056 backtracking of the value have not yet occurred (the demon sends the old 1057 value just before the actual backtracking). It can be examined at the 1058 next break-point. The pop-up menu also shows the current displayed 1059 value, and the previous displayed value for the cell. 1060 1061<P> 1062"), 1063 args:["Terms" : "One or two dimensional array, or List/integer.", 1064 "Name" : "An atomic term."], 1065 resat:" No (but display matrix removed on backtracking).\t\t", 1066 exceptions:[5 : "Invalidly constructed Terms, or non-atomic Name.", 6 : "Name has already been given to another display matrix that is still active."], 1067 eg:" 1068 queens(N, List) :- 1069 length(List, N), 1070 List :: 1..N, 1071 make_display_matrix(List/0, queens), 1072 % sets up a matrix with all variables in 1 row. This is the only 1073 % extra goal that has to be added to enable monitoring 1074 alldistinct(List), 1075 constrain_queens(List), 1076 % Label the variables 1077 labeling(List). 1078 1079 1080 1081 1082", 1083 see_also:[make_display_matrix / 5, kill_display_matrix / 1, dim / 2]]). 1084 1085:- comment(make_display_matrix / 5, [ 1086 summary:" Creates a display matrix of terms that can be monitored with the 1087 graphical ECLiPSe (the predicate will succeed silently in tty ECLiPSe). 1088 1089", 1090 amode:(make_display_matrix(+, +, +, +, +) is det), 1091 desc:html(" Set up a one or two dimensional matrix of terms that can then be 1092 monitored for changes in their values. The terms are either provided in 1093 the form of an array (the nested structure type, compatible with dim/2), 1094 or in the form +List/+Spec, where List is a list of the terms, and Spec 1095 is an integer specifying the number of cells per row of the matrix, 0 1096 means that the matrix is to have only one row (except if the members of 1097 the list are matricies of the same size, in which case a two dimensional 1098 matrix will be created). If List is supplied without a Spec, this is 1099 treated as Spec = 0. Name specifies the name that is associated with 1100 this display matrix, and cannot be used for another display matrix that 1101 is active at the same time in the same module. The name is mapped into a 1102 string internally, so a name that is a atom or number is the same name 1103 as its equivalent string (i.e. 'matrix' and \"matrix\" are the same name). 1104 1105 1106<P> 1107 The terms are monitored by placing a demon suspension on the variables 1108 in each term. When a demon wakes, the new value of the term it is 1109 associated with is sent to the display matrix (and possibly updated, 1110 depending on the interactive settings on the matrix). When the new 1111 value is backtracked, the old value is sent to the display matrix. 1112 The other arguments in this predicate is used to control when the 1113 demon wakes, and what sort of information is monitored. Prio is the 1114 priority that the demon should be suspended at, Type is designed to 1115 specify the attributes that is being monitored (currently all 1116 attributes are monitored, and Type is a dummy argument), CondList is 1117 the suspension list that the demon should be added to. Depending on 1118 these arguments, the level of monitoring can be controlled. Note that 1119 it is possible for the display matrix to show values that are out of 1120 date because the change was not monitored. 1121 1122<P> 1123 The display matrix will be removed on backtracking. However, it will 1124 not be removed if make_display_matrix has been cut. It is possible to 1125 explicitly remove a matrix with kill_display_matrix/1. 1126 1127<P> 1128 Each cell of the display matrix represents one term. The value of the 1129 term is displayed in the cell, and break-points can be set from a pop-up 1130 menu so that execution suspends when an update occurs in a cell. The 1131 term can also be inspected by the inspector. The actual current value of 1132 the term will be examined, which may be different from the value shown 1133 in the cell depending on how often the cell is updated. With breaks, the 1134 changes due to forward execution (further constraining of a variable's 1135 value) and backtracking are shown in different colours. Inspection is 1136 not allowed on a term that has just been backtracked, because the actual 1137 backtracking of the value have not yet occurred (the demon sends the old 1138 value just before the actual backtracking). It can be examined at the 1139 next break-point. The pop-up menu also shows the current displayed 1140 value, and the previous displayed value for the cell. 1141 1142<P> 1143"), 1144 args:["Terms" : "One or two dimensional array, or list or list/integer.", 1145 "Prio" : "An integer.", 1146 "Type" : "An atom.", 1147 "CondList" : "An atom.", 1148 "Name" : "An atomic term."], 1149 1150 resat:" No (but display matrix removed on backtracking).\t\t", 1151 exceptions:[5 : "Type errors in the various arguments.", 6 : "Name has already been given to another display matrix that is still active."], 1152 eg:" 1153 queens(N, List) :- 1154 length(List, N), 1155 List :: 1..N, 1156 make_display_matrix(List/3, 1, any, constrained, queens), 1157 % sets up a matrix with rows of 3 elements. This is the only 1158 % extra goal that has to be added to enable monitoring 1159 alldistinct(List), 1160 constrain_queens(List), 1161 % Label the variables 1162 labeling(List). 1163 1164 1165 1166 1167", 1168 see_also:[make_display_matrix / 2, kill_display_matrix / 1, dim / 2]]). 1169 1170 1171 1172