[m-rev.] for review: Add web browser-based term browsing in the debugger.

[Julien Fischer]

Hi Peter,

On Tue, 15 Aug 2017, Peter Wang wrote:

> I am considering removing the browse --xml command.
> Does it still work,

Presumably.  (I don't have any objections to removing it however.)

> and does anyone use it?

IIRC, you had to provide your own data-type specific stylesheets
for use with it.

> dump --xml will still exist if anyone wants to deal with XML for some
> reason.
>
> ----
>
> Add web browser-based term browsing in the debugger.
>
> browser/browse.m:
>    Add save_and_browse_browser_term_web to be called when
>    "browse --web" is entered at the mdb prompt.
>
>    Add browser_term_to_html_flat_string, a helper predicate for
>    term_to_html.
>
>    Make portray_flat_write_browser_term work take a stream parameter
>    instead of writing to the current output stream. It is called by
>    browser_term_to_html_flat_string, writing to a string builder
>    stream.
>
> browser/browser_info.m:
>    Add web_browser_cmd field to browser_persistent_state.
>
> browser/mdb.m:
> browser/term_to_html.m:
>    Add new module to generate an HTML document. The document contains a
>    JavaScript represention of a Mercury term.
>
>    (The JavaScript string escaping code is adapted from Julien's
>    mercury-json project.)
>
> browser/percent_encoding.m:
>    Add new module to perform percent-encoding.
>
> scripts/mdb_term_browser.css:
> scripts/mdb_term_browser.js:
>    Add JavaScript and CSS files referenced by the generated HTML file
>    to create a tree view of a Mercury term using jstree.
>
> scripts/32px.png:
> scripts/40px.png:
> scripts/throbber.gif:
> scripts/jstree.min.js:
> scripts/jstree.style.min.css:
>    Add local copy of jstree files <https://www.jstree.com/>
>
> scripts/jquery.slim.min.js:
>    Add local copy of jquery <https://jquery.com/>

Mention the above in the README file (in the bit where we list other
third party components and their licenses).

> scripts/Mmakefile:
>    Install the new files into the same directory as mdbrc and other
>    mdb-related files.
>
> trace/mercury_trace_browse.c:
> trace/mercury_trace_browse.h:
> trace/mercury_trace_cmd_browsing.c:
> trace/mercury_trace_cmd_parameter.c:
> trace/mercury_trace_cmd_parameter.h:
> trace/mercury_trace_internal.c:
>    Add "browse --web" and "web_browser_cmd" commands.
>
> doc/user_guide.texi:
>    Document "browse --web" and "web_browser_cmd" commands.
>
> configure.ac:
> scripts/mdbrc.in:
>    Set a reasonable default command to launch a web browser from mdb.
>    (Only tested on Linux.)
>
> diff --git a/NEWS b/NEWS
> index adf897b..dc9f898 100644
> --- a/NEWS
> +++ b/NEWS
> @@ -593,6 +593,8 @@ Change to the Mercury debugger:
>     - Non-canonical output bindings are now printed in solutions.
>     - Underscore variables are no longer printed in solutions.
> 
> +* We have added a "browse --web" command to view terms in a web browser.
> +
> Changes to the extras distribution:
> 
> * We have added support for Unicode and other enhancements to the lex and

...

> new file mode 100644
> index 0000000..ff679c3
> --- /dev/null
> +++ b/browser/term_to_html.m
> @@ -0,0 +1,427 @@
> +%---------------------------------------------------------------------------%

...

> +:- pred char_is_ascii(char::in) is semidet.
> +
> +char_is_ascii(Char) :-
> +    Code = char.to_int(Char),
> +    Code >= 0x00,
> +    Code =< 0x7f.

That is arguably worth having in the char module.

> +:- pred put_unicode_escape(io.output_stream::in, char::in,
> +    io::di, io::uo) is det.
> +
> +put_unicode_escape(Stream, Char, !State) :-
> +    CodePoint = char.to_int(Char),
> +    ( if CodePoint > 0xFFFF then
> +        code_point_to_utf16_surrogates(CodePoint, LS, TS),
> +        put_hex_digits(Stream, LS, !State),
> +        put_hex_digits(Stream, TS, !State)
> +    else
> +        put_hex_digits(Stream, CodePoint, !State)
> +    ).
> +
> +:- pred code_point_to_utf16_surrogates(int::in, int::out, int::out) is det.
> +
> +code_point_to_utf16_surrogates(CodePoint, LS, TS) :-
> +    AdjustedCodePoint = CodePoint - 0x10000,
> +    LS = 0xD800 + (AdjustedCodePoint >> 10),
> +    TS = 0xDC00 + (AdjustedCodePoint /\ 0x3FF).

Do we not provide this predicate (or the equivalent) in the standard
library?

...

> diff --git a/doc/user_guide.texi b/doc/user_guide.texi
> index a067e1d..97b515d 100644
> --- a/doc/user_guide.texi
> +++ b/doc/user_guide.texi
> @@ -3013,8 +3013,8 @@ and @samp{-v} or @samp{--verbose} specify the format to use for printing.
> @c The options @samp{-f} or @samp{--flat}, @samp{-p} or @samp{--pretty},
> @c and @samp{-v} or @samp{--verbose} specify the format to use for printing.
> @sp 1
> - at item browse [-fpvx] @var{name}[@var{termpath}]
> - at itemx browse [-fpvx] @var{num}[@var{termpath}]
> + at item browse [-fpvxw] @var{name}[@var{termpath}]
> + at itemx browse [-fpvxw] @var{num}[@var{termpath}]
> @kindex browse (mdb command)
> Invokes an interactive term browser to browse
> the value of the variable in the current environment
> @@ -3034,13 +3034,15 @@ variable to an XML file and then invoke an XML browser on the file.
> The XML filename as well as the command to invoke the XML browser can
> be set using the @samp{set} command.  See the documentation for @samp{set}
> for more details.
> +The @samp{-w} or @samp{--web} option tells mdb to dump the value of the
> +variable to an HTML file and then invoke a web browser on the file.

     ... on that file.

(And similarly below.)

That looks fine otherwise.

Julien.