diff --git a/docs/_html/index.html b/docs/_html/index.html index 3103706..566b945 100644 --- a/docs/_html/index.html +++ b/docs/_html/index.html @@ -11,7 +11,7 @@

OCaml package documentation

    -
  1. ppx_minidebug 0.6.2
    2. +
  2. ppx_minidebug 0.7.0
diff --git a/docs/_html/ppx_minidebug/Minidebug_runtime/PrintBox/index.html b/docs/_html/ppx_minidebug/Minidebug_runtime/PrintBox/index.html index d028267..7c313cd 100644 --- a/docs/_html/ppx_minidebug/Minidebug_runtime/PrintBox/index.html +++ b/docs/_html/ppx_minidebug/Minidebug_runtime/PrintBox/index.html @@ -15,4 +15,4 @@ descr:string -> pp:(Stdlib.Format.formatter -> 'a -> unit) -> v:'a -> - unit
val log_value_show : descr:string -> v:string -> unit
val exceeds_max_nesting : unit -> bool
val exceeds_max_children : unit -> bool
val no_debug_if : bool -> unit

When passed true within the scope of a log subtree, disables the logging of this subtree and its subtrees. Does not do anything when passed false (no_debug_if false does not re-enable the log).

val to_html : bool Stdlib.ref

While true, logs are generated as html; if false, as monospaced text.

val boxify_sexp_from_size : int Stdlib.ref

If positive, Sexp.t-based logs with this many or more atoms are converted to print-boxes before logging.

+ unit
val log_value_show : descr:string -> v:string -> unit
val exceeds_max_nesting : unit -> bool
val exceeds_max_children : unit -> bool
val no_debug_if : bool -> unit

When passed true within the scope of a log subtree, disables the logging of this subtree and its subtrees. Does not do anything when passed false (no_debug_if false does not re-enable the log).

val to_html : bool Stdlib.ref

While true, logs are generated as html; if false, as monospaced text.

val boxify_sexp_from_size : int Stdlib.ref

If positive, Sexp.t-based logs with this many or more atoms are converted to print-boxes before logging.

val highlight_terms : Re.re option Stdlib.ref

Uses a highlight style for logs on paths ending with a log matching the regular expression.

val exclude_on_path : Re.re option Stdlib.ref

Does not propagate the highlight status from child logs through log headers matching the given regular expression.

diff --git a/docs/_html/ppx_minidebug/Minidebug_runtime/index.html b/docs/_html/ppx_minidebug/Minidebug_runtime/index.html index 6a9cca5..e1e1ac3 100644 --- a/docs/_html/ppx_minidebug/Minidebug_runtime/index.html +++ b/docs/_html/ppx_minidebug/Minidebug_runtime/index.html @@ -9,6 +9,8 @@ ?time_tagged:bool -> ?max_nesting_depth:int -> ?max_num_children:int -> + ?highlight_terms:Re.t -> + ?exclude_on_path:Re.t -> ?for_append:bool -> ?boxify_sexp_from_size:int -> string -> @@ -17,6 +19,8 @@ ?time_tagged:bool -> ?max_nesting_depth:int -> ?max_num_children:int -> + ?highlight_terms:Re.t -> + ?exclude_on_path:Re.t -> unit -> (module Debug_runtime_cond)

Creates a PrintBox-based debug runtime. By default it will log to stdout and will not be time tagged.

val debug_flushing : ?debug_ch:Stdlib.out_channel -> diff --git a/docs/_html/ppx_minidebug/index.html b/docs/_html/ppx_minidebug/index.html index 4df62b2..9d84a9e 100644 --- a/docs/_html/ppx_minidebug/index.html +++ b/docs/_html/ppx_minidebug/index.html @@ -1,12 +1,12 @@ -index (ppx_minidebug.index)

ppx_minidebug usage

ppx_minidebug traces selected code if it has type annotations. ppx_minidebug offers three ways of instrumenting the code: %debug_pp and %debug_show based on deriving.show, and %debug_sexp based on sexplib0 and ppx_sexp_conv. The syntax extension expects a module Debug_runtime in the scope. The ppx_minidebug.runtime library offers three ways of logging the traces, as functors generating Debug_runtime modules given an output channel (e.g. for a file).

Take a look at ppx_debug which is significantly more powerful!

See Minidebug_runtime for the provided loggers.

Usage

Try opam install ppx_minidebug to install from the opam repository. To install `ppx_minidebug` from sources, download it with e.g. gh repo clone lukstafi/ppx_minidebug; cd ppx_minidebug and then either dune install or opam install ..

To use ppx_minidebug in a Dune project, add/modify these stanzas: (preprocess (pps ... ppx_minidebug)), and (libraries ... ppx_minidebug.runtime).

To trace a function, you have to type-annotate the function result. To trace an argument of a traced function, or a let-binding, you need to type-annotate it. You can control how much gets logged by adding or removing type annotations.

Tracing only happens in explicitly marked scopes, using the extension points: %debug_pp, %debug_this_pp, %debug_show, %debug_this_show (based on printing functionality provided by deriving.show), %debug_sexp, %debug_this_sexp (using functionality provided by sexplib0 and ppx_sexp_conv). See examples in the test directory.

The %debug_this variants are intended only for let-bindings: let%debug_this v: t = compute value in body will trace v and the type-annotated bindings and functions inside compute value, but it will not trace body.

Example setting up a logger printing to the screen:

module Debug_runtime = (val Minidebug_runtime.debug_flushing ())
+index (ppx_minidebug.index)
ppx_minidebug usage
ppx_minidebug traces selected code if it has type annotations. ppx_minidebug offers three ways of instrumenting the code: %debug_pp and %debug_show based on deriving.show, and %debug_sexp based on sexplib0 and ppx_sexp_conv. The syntax extension expects a module Debug_runtime in the scope. The ppx_minidebug.runtime library offers three ways of logging the traces, as functors generating Debug_runtime modules given an output channel (e.g. for a file).
Take a look at ppx_debug which is significantly more powerful!
See Minidebug_runtime for the provided loggers.
Usage
Try opam install ppx_minidebug to install from the opam repository. To install `ppx_minidebug` from sources, download it with e.g. gh repo clone lukstafi/ppx_minidebug; cd ppx_minidebug and then either dune install or opam install ..
To use ppx_minidebug in a Dune project, add/modify these stanzas: (preprocess (pps ... ppx_minidebug)), and (libraries ... ppx_minidebug.runtime).
To trace a function, you have to type-annotate the function result. To trace an argument of a traced function, or a let-binding, you need to type-annotate it. You can control how much gets logged by adding or removing type annotations.
Tracing only happens in explicitly marked scopes, using the extension points: %debug_pp, %debug_this_pp, %debug_show, %debug_this_show (based on printing functionality provided by deriving.show), %debug_sexp, %debug_this_sexp (using functionality provided by sexplib0 and ppx_sexp_conv). See examples in the test directory.
The %debug_this variants are intended only for let-bindings: let%debug_this v: t = compute value in body will trace v and the type-annotated bindings and functions inside compute value, but it will not trace body.
Example setting up a logger printing to the screen:
module Debug_runtime = (val Minidebug_runtime.debug_flushing ())
 let%debug_show test_logging: string = "Hello World"
Example setting up a logger printing to a file:
module Debug_runtime =
   Minidebug_runtime.Flushing((val Minidebug_runtime.debug_ch "debugger_flushing.log"))
 let%debug_show test_logging: string = "Hello World"
Example setting up a logger printing to an HTML file -- this is only possible with the PrintBox runtime. In this example, we also configure the converting the sexp-based logs to the PrintBox format (when they have at least 50 atoms). This means that both the log tree structure and the structure of large values can be incrementally explored using collapsible trees in an HTML renderer.
module Debug_runtime =
   Minidebug_runtime.PrintBox ((val Minidebug_runtime.debug_ch "debug.html"))
 let () = Debug_runtime.to_html := true
 let () = Debug_runtime.boxify_sexp_from_size := 50
debug_html is a configurable shorthand for the above setup:
module Debug_runtime = (val Minidebug_runtime.debug_html "debug.html")
Similarly, debug and debug_flushing are configurable shorthands that default to logging to stdout (but accept a `~debug_ch` argument).
Debugging infinite loops
Computation can be optionally interruped using the ~max_nesting_depth and ~max_num_children settings. The first raises a failure when the nesting of logs exceeds the given threshold, the second raises a failure when the number of log entries under a single parent exceeds the threshold. E.g.:
module Debug_runtime =
-  (val Minidebug_runtime.debug_html ~max_nesting_depth:20 ~max_num_children:50 "debug.html")
The cutoff points are indicated in the logs.
VS Code suggestions
Add / remove type annotations and visit files using VOCaml
VOCaml helpers for coding in OCaml provide commands to add and remove annotations on selected bindings. They can be used to introduce logging, tune it, and cleanup afterward. It also has a command to populate the _Quick Open_ dialog with a file name and location from a line under cursor. It can be used to jump to the source code from a log file.
Note that you can add and remove type annotations using VSCode OCaml Platform's code actions, and the Find and Transform suggestion below is a more flexible go-to-file solution -- so VOCaml is somewhat redundant. But, it is still valuable: (1) it annotates multiple let-bindings at once in a selection, and (2) it annotates the argument types and the return type of a function (as required by ppx_debug) when invoked on a function definition.
Visualize the flame graph using Log Inspector
Log Inspector (sub-millisecond)'s main feature is visualizing timestamped logs as flame graphs. To invoke it in VS Code, go to the Minidebug_runtime.Flushing-style logs file, press crtl+shift+P, and execute the command Log Inspector: Draw.
The sub-millisecond functionality is now upstreamed to Log Inspector.
Go to file location using Find and Transform
This will expand your general-purpose VS Code toolbox!
Find and Transform is a powerful VS Code extension. I put the following in my `keybindings.json` file (command: Open Keyboard Shortcuts (JSON)):
{
+  (val Minidebug_runtime.debug_html ~max_nesting_depth:20 ~max_num_children:50 "debug.html")
The cutoff points are indicated in the logs.
Searching and navigating the logs
Currently (since 0.7.0) there is just one support mechanism for taming complex logs: a highlight_terms regular expression in the PrintBox runtime. Paths to logs that match highlight_terms are printed with a frame / border: around the log and around summaries on the path to the log. A corresponding setting `exclude_on_path` will disable highlighting on logs (summaries) this regular expression matches on, regardless of children. Therefore, `exclude_on_path` stops the propagation of highlights upward.
VS Code suggestions
Add / remove type annotations and visit files using VOCaml
VOCaml helpers for coding in OCaml provide commands to add and remove annotations on selected bindings. They can be used to introduce logging, tune it, and cleanup afterward. It also has a command to populate the _Quick Open_ dialog with a file name and location from a line under cursor. It can be used to jump to the source code from a log file.
Note that you can add and remove type annotations using VSCode OCaml Platform's code actions, and the Find and Transform suggestion below is a more flexible go-to-file solution -- so VOCaml is somewhat redundant. But, it is still valuable: (1) it annotates multiple let-bindings at once in a selection, and (2) it annotates the argument types and the return type of a function (as required by ppx_debug) when invoked on a function definition.
Visualize the flame graph using Log Inspector
Log Inspector (sub-millisecond)'s main feature is visualizing timestamped logs as flame graphs. To invoke it in VS Code, go to the Minidebug_runtime.Flushing-style logs file, press crtl+shift+P, and execute the command Log Inspector: Draw.
The sub-millisecond functionality is now upstreamed to Log Inspector.
Go to file location using Find and Transform
This will expand your general-purpose VS Code toolbox!
Find and Transform is a powerful VS Code extension. I put the following in my `keybindings.json` file (command: Open Keyboard Shortcuts (JSON)):
{
   "key": "alt+q",
   "command": "findInCurrentFile",
   "args": {