Pack debug_call -- prolog/debug

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, enum, testo/[a,b,c] ).
% Starting enumeration of list: testo
% 1.a
% 2.b
% 3.c
% Ended enumeration of list: testo
true.

?- debug_call( ex, info, 'My message is ~w.'/long ).
% My message is long.
true.    % message above is printed in informational colour

?- 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; - 1.3 2020/3/7; - 1.4 2020/9/18; - 1.5 2022/12/29
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:5:0,
D = date(2022,12,29).

debuc(+Topic, +Goal)

debuc(+Topic, +Goal, +Args)

debuc(+Topic, +Goal, +Pfx, +Args)

Shorthands for debug_call/2,3,4 and debug/1.

author: - nicos angelopoulos
version: - 0:1 2020/9/9

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 arguments 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, +Pfx, +Arg)

Automates often used debug calls. When Pfx is missing it is assumed to be ''. Predicate can also be used to call arbitrary Goal and then print a message after it has successfull completed. As of 1.2 it can also work as a replacement to debug/3. With 1.3 the debuc/3 shorthand was introduced.

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
enum: print lists and deconstructed terms, where each item is prefixed with an index number
goal: anything that does n't match any of the above is retrived as call(Goal)
info: print using informational machinery (usually different/green colour, to debug's blue) term should Mess/Args in the debug/3 version
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)
options: options used on call to predicate
pwd: message about current dir Location (=Arg), (if Arg == false, location is not shown)- see examples
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 (Wch) of a task. Other values for Wch are allowed but printed as they come. Arg can be a term (as of Version 1.5).
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]

 ?- debuc( ex, pwd, here ).
 % Pwd at, here, is: '/Users/nicosangelopoulos/.local/share/swi-prolog/pack/Downloads/bio_db_repo-publish/bio_db_repo-20.09.14/data/hs/maps/hgnc/'
 true.
 
 ?- debuc( ex, pwd, false ).
 % Pwd: '/Users/nicosangelopoulos/.local/share/swi-prolog/pack/Downloads/bio_db_repo-publish/bio_db_repo-20.09.14/data/hs/maps/hgnc/'
 true.

At some point around SWI-Prolog 8, behaviour of debug/3 changed in being more strict about messages with no arguments. As of version 1.2 debug_call/3 can act as a replacement of debug/3 but with the old behaviour.

 ?- debug( ex, 'Messagging...', true ).
 Messagging...
 [[ EXCEPTION while printing message 'Messagging...'
       with arguments user:true:
       raised: format('too many arguments')
    ]]
 
 true.
 
 ?- debug_call( ex, 'Messagging...', true ).
 % Messagging...
 true.

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 2014/??/?? added ns_sel; - 1.1 2018/03/20 prefer +2 arity in debug_call/2; - 1.2 2020/03/07 now can be used as a replacement for debug/3 (but with old 3rd arg behaviour, allowing eg 'true').; - 1.3 2020/09/14 added canned calls info and enum, debuc/2,3,4
See also: - debuc/3 (shorthand for debug_call/3).

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]. As of v0.2 Clrs can be a single colour.

 ?- debug( dbg ).
 ?- debug_consec( dbg, 'what:~w', when ).
 % what: when            <- in blue

 ?- debug_consec( dbg, 'what:~w', when ).
 % what: when            <- in magenta

 ?- debug_consec( dbg, [blue,green], 'what:~w', when ).
 % what: when            <- in blue

 ?- debug_consec( dbg, [blue,green], 'what:~w', when ).
 % what: when            <- in green

Version 0.2

 ?- debug_consec( dbg, magenta, 'what:~w', when ).
 % what: when            <- in magenta

author: - nicos angelopoulos
version: - 0.2 2019/12/29; - 0.1 2014/7/24

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

debug_call(Arg1, Arg2, Arg3, Arg4)
debuc(Arg1)
debuc(Arg1, Arg2, Arg3)
debuc(Arg1, Arg2, Arg3, Arg4)
debug_chain(Arg1, Arg2, Arg3)
debug_consec(Arg1, Arg2, Arg3, Arg4)