:- module(coverage).
:- export result / 0.
:- export result_body / 3.
:- export result / 2.
:- export result_body / 2.
:- export result / 1.
:- export ccompile_body / 3.
:- export ccompile / 2.
:- export ccompile_body / 2.
:- export ccompile / 1.
:- export point / 2.
:- export point / 1.
:- export print_counters / 0.
:- export reset_counters / 0.
:- tool(result / 2,result_body / 3).
:- tool(result / 1,result_body / 2).
:- tool(ccompile / 2,ccompile_body / 3).
:- tool(ccompile / 1,ccompile_body / 2).
:- tool(point / 1,point / 2).
:- comment(result_body / 3, hidden).
:- comment(result_body / 2, hidden).
:- comment(ccompile_body / 3, hidden).
:- comment(ccompile_body / 2, hidden).
:- comment(point / 2, hidden).
:- comment(author, "Joachim Schimpf, based on ideas by Helmut Simonis").
:- comment(copyright, "Cisco Systems, Inc.").
:- comment(date, "$Date: 2006/12/01 14:12:18 $").
:- comment(summary, "Tool for obtaining code coverage information").
:- comment(desc, html("<P>\n\tThis is a tool for obtaining code coverage information, i.e.\n\tinformation about which points in the code were executed how\n\toften during a particular run of the program.\n</P><P>\n\tThe usage is as follows:\n\t<OL>\n\t<LI>Load the coverage library\n\t<PRE>\n\t?- lib(coverage).\n\t</PRE>\n\t<LI>Compile your program with the coverage compiler\n\t<PRE>\n\t?- coverage:ccompile(my_program).\n\t</PRE>\n\t<LI>Run the query which you want to examine\n\t<PRE>\n\t?- my_query(X,Y,Z).\n\t</PRE>\n\t<LI>Generate an html file containing the results. E.g. the following\n\twill create the result file coverage/my_program.html:\n\t<PRE>\n\t?- coverage:result(my_program).\n\t</PRE>\n\t<LI>View the result file using any browser. The result file\n\tcontains a pretty-printed form of the source, annotated with\n\tthe values of the code coverage counters.\n\t</OL>\n</P><P>\n\tBy default, code coverage counters are inserted before and after\n\tevery subgoal in the code. For instance, in the clause\n<PRE>\n\tp :- q, r, s.\n</PRE>\n\tfour counters would be inserted: before the call to q, between\n\tq and r, between r and s, and after s:\n<PRE>\n\tp :- point(1), q, point(2), r, point(3), s, point(4).\n</PRE>\n\tThis is the most precise form provided. The counter values do not\n\tonly show whether all code points were reached, they also show whether\n\tsubgoals ever failed or aborted (in that case the counter before\n\ta subgoal will have a higher value than the counter after it).\n\tFor example, the result of running the above code may look like:\n<PRE>\n\tp :- <span style=\"color:black; font-weight:bold; background-color:limegreen\"> 43 </span> q, <span style=\"color:black; font-weight:bold; background-color:limegreen\"> 25 </span> r, <span style=\"color:black; font-weight:bold; background-color:limegreen\"> 25 </span> s <span style=\"color:black; font-weight:bold; background-color:red\"> 0 </span>.\n</PRE>\n\twhich would indicate that q was called 43 times, but succeeded\n\tonly 25 times, r was called 25 times and succeeded always, and\n\ts was called 25 times and never succeeded.  Coverage counts of\n\tzero are displayed in red because they indicate unreached code.\n</P><P>\n\tIf one is only interested in knowing whether all code was covered,\n\tit is not necessary to have all these counters. point(1) and point(4)\n\tare enough to know whether q, r and s were successfully executed.\n\tThe option <B>blocks_only</B> implements this: counters only\n\tget inserted at the beginning and at the end of conjunctions\n\t(comma-separated goal sequences), i.e. in the example:\n<PRE>\n\tp :- point(1), q, r, s, point(4).\n</PRE>\n\tFor big programs, the presence of counters at the end of\n\tclauses can cause problems because they prevent tail-recursion\n\toptimization and may lead to stack overflows.  If that should\n\tbe the case, exit-counters can be disabled by setting the\n\t<B>exit_counters</B> option to <B>off</B>, leading to the following\n\tincomplete instrumentation:\n<PRE>\n\tp :- point(1), q, point(2), r, point(3), s.\n</PRE>\n</P><P>\n\tNote on the analysis of large, structured applications: \n\tLarger applications often consist of several modules which get\n\tcompiled implicitly through use_module/1 directives.  In this\n\tcase, the module(s) that one wants to compile in coverage mode\n\tcan be either compiled with ccompile/1 in advance (before\n\tloading the main application module), or afterwards (in which\n\tcase ccompile/1 will replace the previously compiled normal\n\tcode with coverage-code).\n</P><P>\n\tLimitation: The current implementation cannot deal with multiple\n\t(non-module) files that are ccompiled into the same module.\n</P>")).
:- comment(ccompile / 1, [summary : "Compile a file, inserting code coverage counters", args : ["File" : "Atom or string"], amode : ccompile(+), see_also : [ccompile / 2, library(coverage), result / 1, result / 2], desc : html("\n    This is a variant of the ECLiPSe compiler that inserts code coverage\n    counters into the compiled code. This code can then be run, and the\n    results analysed by printing them using coverage:result/1.\n    ")]).
:- comment(ccompile / 2, [summary : "Compile a file, inserting code coverage counters", args : ["File" : "Atom or string", "OptionList" : "List of Name:Value pairs"], amode : ccompile(+, +), see_also : [ccompile / 1, library(coverage), result / 1, result / 2], desc : html("<P>\n    This is a variant of the ECLiPSe compiler that inserts code coverage\n    counters into the compiled code. This code can then be run, and the\n    results analysed by printing them using coverage:result/1.\n</P><P>\n    Options to modify the behaviour of the code coverage library are:\n<DL>\n    <DT>exit_counters (default:on)<DD>\n    \tSetting this to 'off' will suppress coverage counters at the end of\n\tconjunctions (comma-sequences of subgoals).\n    <DT>blocks_only (default:off)<DD>\n    \tSetting this to 'on' will leave only coverage counters at the\n\tbeginning and at the end of conjunctions (comma-sequences of\n\tsubgoals) and suppress all others.\n    <DT>macro_expansion (default:off)<DD>\n\tThis options affects only the printing of the result (html) file.\n\tBy default, read-macros are not expanded in this output.  In rare\n\tcases, where macro expansion would affect the placement of coverage\n\tcounter positions, it may be necessary to set this option to 'on'\n\tin order to display the counter values at the correct positions\n\tin the code.\n    <DT>goal_expansion (default:on)<DD>\n    \tSetting this to 'off' will suppress goal expansion (inlining)\n\tduring compilation. This may be necessary when the processed\n\tcode contains predicates that get executed at compile time.\n    <DT>verbose (default:off)<DD>\n    \tIf set to 'on', the coverage preprocessor will print predicate\n\tnames as they are processed (to log_output).\n</DL>\n</P>\n    ")]).
:- comment(reset_counters / 0, [summary : "Reset all the coverage counters to zero", args : [], see_also : [ccompile / 1, result / 1], desc : html("\n    The system maintains code coverage counters for all code compiled\n    with coverage:ccompile/1. These counters get incremented when this\n    code is run, and get reset implicitly when the results are output\n    using coverage:result/1.\n    ")]).
:- comment(result / 0, [summary : "Pretty-print all files with code coverage results", args : [], see_also : [result / 1, result / 2, library(coverage), library(pretty_printer), ccompile / 1], desc : html("<P>\n    This will pretty-print all source files that have been previously\n    compiled with ccompile/1,2. For details see result/1.\n</P>\n    ")]).
:- comment(result / 1, [summary : "Pretty-print a file, including any code coverage results", args : ["File" : "Atom or string"], amode : result(+), see_also : [result / 2, library(coverage), library(pretty_printer), ccompile / 1], desc : html("<P>\n    This will pretty-print the given source file, annotated with the\n    values of code coverage counters. The resulting .html file will be\n    placed in a sub-directory called 'coverage', relative to File.\n    See result/2 for options to modify the output.\n</P><P>\n    This predicate only makes sense if File has previously been compiled\n    in coverage mode (using coverage:ccompile/1,2), and the code has been\n    run in order to obtain values for the coverage counters.\n</P>\n    ")]).
:- comment(result / 2, [summary : "Pretty-print a file, including any code coverage results", args : ["File" : "Atom or string", "OptionList" : "List of Name:Value pairs"], amode : result(+, +), see_also : [result / 1, pretty_printer : pretty_print / 2, ccompile / 1, library(coverage), library(pretty_printer)], desc : html("<P>\n    This will pretty-print the given source file, annotated with the\n    values of code coverage counters. By default, the resulting .html\n    file will be placed in a sub-directory called 'coverage', relative\n    to File.\n</P><P>\n    OptionList is a list of options identical to the one accepted by\n    pretty_print/2 in the library(pretty_printer), and can be used to\n    modify the output style and the location of the output file.\n</P><P>\n    This predicate only makes sense if File has previously been compiled\n    in coverage mode (using coverage:ccompile/1,2), and the code has been\n    run in order to obtain values for the coverage counters.\n    ")]).
