debug_call.pl -- Debugging with calls.

Avoids running goals to produce output that is only relevant while debugging. Includes pre-canned, often used calls.

Examples

?- debug( ex ).
?- debug_call( ex, length, '', list1/[x,y,z] ).
% Length for list, list1: 3

?- debug_call( ex, length, 'some prefix', [list1,list2]/[[x,y,z],[a,b,c]] ).
% some prefix lengths for lists, list1: 3, list2: 3

?- debug_call( ex, dims, [m1,m2]/[[a(x),a(y),a(z)],[xy(a,b),xy(c,d),xy(e,f)]] ).
%  Dimensions for matrices,  (m1) nR: 3, nC: 1. (m2) nR: 3, nC: 2.

?- debug_call( ex, wrote, loc(file,csv) ).
% Could not locate wrote on file specified by: file, and extensions: csv
?- csv_write_file( 'file.csv', [] ).

?- debug_call( ex, wrote, loc(file,csv) ).
% Wrote on file: '/home/nicos/pl/lib/src/trace/file.csv'

?- debug_call( ex, task(stop), 'write on file' ).
At 15:44:1 on 2nd of Jul 2014 finished task: write on file.

Variable topics

This library avoids the messy way in which package(debug) deals with variable debug topics. That is, their term expansion and subsequent pattern matching mishandles goals of the form debugging/1 and debug/3 that have an unbound variable in the 1st argument. debug_calls uses dynamic -..

Pack info

author

- nicos angelopoulos

version

- 0.1 2016/3/5

- 0.2 2016/11/01

- 0.3 2017/3/9

See also

- http://stoics.org.uk/~nicos/sware/debug_call/

To be done

- options_debug( Opts, Mess, Args ) only writes if Opts contains debug(true). maybe this should be part of pack(options)

- provide a way to remove lib(debug)'s expansions

debug_call_version(-Version, -Date)

Current version and release date for the library.

debug_call(+Topic, +Goal)

Only call debug if we are debugging Topic.

propose this to be included to debug.pl

debug_chain(+TopicCond, +TopicDep)

debug_chain(+TopicCond, +TopicDep, -TDprior)

If already debugging TopicCond, then also start debugging TopicDep ). TDprior is true if TopicDep was already debugging, else is false. Current implementation sets TDprior to true whenever Topic is not debugged, as it assumes that this value best suit independent fluctuation of TopicDep. Only in the case of debug_chain/2, TopicDep can be a list.

author

- nicos angelopoulos

version

- 0.1 2014/4/4

- 0.2 2016/11/1

See also

- debug_set/2

debug_message(+Topic, +Mess, +Args)

A wrap around debug/3 that calls it by constructing the term on-the-fly. So that lib(debug) does not create a record by inspecting the term (via expansion). Particularly useful in sending uninstantiated Topics.

author

- nicos angelopoulos

version

- 0.1 2016/11/1

debugging_topic(?Topic)

A wrap around debugging/1 that calls it by constructing the term on-the-fly. So that lib(debug) does not create a record by inspecting the term (via expansion). Particularly useful in sending uninstantiated Topics.

author

- nicos angelopoulos

version

- 0.1 2016/11/1

debugging_status(+Topic, -Status)

Status == true iff debugging(Topic) succeeds. Else, it is false. Similar to debugging/2, but does not fail for undefined Topic.

 ?- debug( something ).
 true.
 ?- debugging_status( something, Some ).
 Some = true.
 ?- debugging_status( some_else, Else ).
 Else = false.

author

- nicos angelopoulos

version

- 0.1 2014/7/23

debug_set(+Prior, +Topic)

Reset Topic according to Prior: true sets Topic to on and false turns Topic off.

 ?- nodebug( chained ).
 true.
 ?- debug( testo ).
 Warning: testo: no matching debug topic (yet)
 true.
 ?- debug( chained, 'debugs chains 1', [] ).
 true.
 ?- debug_chain( testo, chained, Prior ).
 Prior = false.
 ?- debug( chained, 'debugs chains 2', [] ).
 % debugs chains 2
 true.
 ?- Prior = false, debug_set( Prior, chained ).
 Prior = false.
 ?- debug( chained, 'debugs chains 3', [] ).
 true

author

- nicos angelopoulos

version

- 0.1 2014/7/23

- 0.2 2016/8/22, Prior == true used to do nothing, now it turns topic on. also renmaed from debug_set/2.

See also

- debug_chain/3

debug_topic(+Topic, +Opts, -Restore)

Start debugging Topic if options(debug(true),Opts), with Restore being instantiated to a term that can be used to restore the original debug state of Topic (see options_restore/2). If options(debug(false),Opts) then Topic is stopped from being debugged (Restore still holds the correct term for restoring debugging state for topic to precall status).

?- assert( ( on_t(I,Topic) :- (debugging(Topic) -> write(I-y(Topic)) ; write(I-n(Topic))), nl ) ).
?- T = options, debug(T), on_t(1,T), debug_topic(T,[debug(false)],R), on_t(2,T), debug_set(R,T), on_t(3,T).
1-y(options)
2-n(options)
3-y(options)
T = options,
R = true.

?- T = options, nodebug(T), on_t(1,T), debug_topic(T,[debug(true)],R), on_t(2,T), debug_set(R,T), on_t(3,T).
1-n(options)
2-y(options)
3-n(options)
T = options,
R = false.

author

- nicos angelopoulos

version

- 0.1 2016/8/22

debug_topic(+Flag, +Topic)

Start debugging Topic if Flag == true, and stop debugging if Flag == false.

 ?- debug_topic( true, example ).

author

- nicos angelopoulos

version

- 0.1 2014/12/10

- 0.2 2016/08/22, added nodebug/1 when Flag == false

See also

- options_append/4

debug_on(+Topic)

As debug/1, but do not print warning if topic is not known.

debug_portray(+Topic, +Term)

Call portray_clause(Term) if we are debugging Topic.

author

- nicos angelopoulos

version

- 0.1

debug_call(+Topic, +Goal, +Arg)

debug_call(+Topic, +Goal, +Mess, +Arg)

Automates often used debug calls. When Pfx is missing it is assumed to be ''. It can also be used to call arbitrary Goal and then print a message after it has successfull completed.

When Goal is a known abbreviation, then Arg usually qualifies the output generated. When Goal is of the form call(Goal), Arg will be passed to debug(Topic,Mess,Arg).

Goal in:

length

prints the lenghts of a bunch of lists. Args should be ListNames/Lists. uses non list ListNames if debuging the length of a single list, in which case message in the singular is used.

list

writes contents of list with header and footer. Arg should be of the form Hdr/Ftr/List, else it is translated as Hdr/''/List or ''/''/List. If Hdr or Ftr are '' then that part of the message is skipped

dims

prints the dimensions of matrix, see mtx_dims/3

wrote

reports the writting of output on a file. Arg should be file specification suitable for locate/3. Either loc(File,Exts) or simply File in which case Exts = ''.

read

reports reading from a file. Arg should be file specification suitable for locate/3. Either loc(File,Exts) or simply File in which case Exts = ''.

task(Wch)

time of start/stop of a task. Other values are allowed put printed as is.

start

translates to starting ~Arg

end

translates to finishing ~Arg

call(Goal)

call Goal before printing debugging message debug( Topic, Mess, Args). (Goal is called in non-deterministic context).

pwd

message about the current directory location (if Arg == false, it is ignored)

goal

anything that does n't match any of the above is retried as call(Goal)

 ?- debug( ex ).
 ?- debug_call( ex, length, '', list1/[x,y,z] ).
 % Length for list, list1: 3
  
 ?- debug_call( ex, length, 'some prefix', [list1,list2]/[[x,y,z],[a,b,c]] ).
 % some prefix lengths for lists, list1: 3, list2: 3
 
?- debug_call( ex, wrote, loc(file,csv) ).
% Could not locate wrote on file specified by: file, and extensions: csv
?- csv_write_file( 'file.csv', [] ).

?- debug_call( ex, wrote, loc(file,csv) ).
% Wrote on file: '/home/nicos/pl/lib/src/trace/file.csv'

?- debug_call( ex, task(stop), 'write on file' ).
% At 15:44:1 on 2nd of Jul 2014 finished task: write on file.
    
?- debug_call( ex, (length([a,b,c],L),write(len(L)),nl) ).
len(3)
L = 3.

author

- nicos angelopoulos

version

- 0.1 2014/03/27

- 0.2 2014/04/24 added wrote

- 0.3 2014/07/2 added task

- 0.4 2014/09/22 renamed from debug_call/3