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.

?- assert( (simple_mess(KVs,Mess,Args):- KVs =[a=A,b=B], atom_concat(A,B,Mess), Args=[]) ).
?- debug_call( ex, simple_mess([a=1,b=2],

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
- 1.1 2018/3/20
- 1.2 2019/4/22
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_version( V, D ).
V = 1:2:0,
D = date(2019,4,22).
 debug_call(+Topic, +Goal)
Only call debug if we are debugging Topic.

If Goal with arity +2 is available call that instead of Goal with extra arguemnts Mess and Args that will be passed to debug/3. If the goal (original or +2) fail, nothing is printed by debug_call and the debug_call(T,G) itself succeeds.

 ?- goal( Goal, Mess, Args ).

Examples

 ?- assert( (simple_mess(KVs,Mess,Args):- KVs =[a=A,b=B], atom_concat(A,B,Mess), Args=[]) ).
 ?- debug_call( ex, simple_mess([a=1,b=2],
author
- nicos angelopoulos
version
- 0.2 2018/3/20
 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:

call(Goal)
call Goal before printing debugging message debug( Topic, Mess, Args). (Goal is called in non-deterministic context).
dims
prints the dimensions of matrix, see mtx_dims/3
end
translates to finishing ~Arg or starting ~Topic if Arg == true
goal
anything that does n't match any of the above is retried as call(Goal)
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
ns_sel
first argument is the item selected from second arg list (only reported if 2nd arg is not a singleton (ns)) accepts 2 optional args, 3rd is the token of what is selected (false for printing nothing on the subject, default) and 4th is whether to report if the 2nd argument is indeed a singleton (default: false)
ns_sel(true)
first argument is the item selected from second arg list. reports differently if 2nd arg is a singleton, but always does report
odir
output directory (Arg should exist and be a directory)
pwd
message about the current directory location (if Arg == false, it is ignored)
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 = ''.
start
translates to starting ~Arg or starting ~Topic if Arg == true
task(Wch)
time of start/stop of a task. Other values are allowed put printed as is.
term
simply spew the input term
var
reports variable name (arg(1)) and its current instantiation (arg(2))
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 = ''.
 ?- 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.

?-  Etcs = [suv-17.09.26.txg,suv-17.09.21.txg], Etc = suv-17.09.26.txg,
    debug_call( suv, ns_sel, c(Etc,Etcs,'suv file',true) )
 Continuing with: suv file, as: suv-17.09.26.txg, from non singleton list: [suv-17.09.26.txg,suv-17.09.21.txg]
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
- 0.5 current added ns_sel
- 1.1 2018/3/20 prefer +2 arity in debug_call/2
 debug_consec(+Topic, +Mess, +Args)
 debug_consec(+Topic, +Clrs, +Mess, +Args)
Alternate the colours of printing messages on Topic, from those in Clrs. When missing these are [blue,magenta].
 ?- debug( dbg ).
 ?- debug_consec( dbg, 'what:~w', when' ).
 % what: where   %  % in blue
 ?- debug_consec( dbg, 'what:~w', when' ).
 % what: where   %  % in magenta
 ?- debug_consec( dbg, 'what:~w', when' ).
 % what: where   %  % in blue
author
- nicos angelopoulos
version
- 0.1 2014/7/24