Fixes #51: get rid of the _this_ infix

CHANGELOG.md

@@ -6,6 +6,7 @@ Great simplification: release 2.0 has in some regards less flexibility than earl
 
 - Move `no_debug_if` to the generic interface (the last remaining non-config functionality missing from it). It's ignored (no-op) for the flushing backend.
 - Move to linear log levels per-entry and per-log, where an unspecified log level inherits from the entry it's in, determined statically.
+- Remove `_this_` infix and make all extension points behave as `_this_` (not extend to bodies of toplevel bindings).
 
 ## [1.6.1] -- 2024-08-21
 

README.md

@@ -151,7 +151,7 @@ For example:
 ```ocaml
 module Debug_runtime =
   (val Minidebug_runtime.debug ~highlight_terms:(Re.str "3") ~values_first_mode:true ())
-let%debug_this_show rec loop_highlight (x : int) : int =
+let%debug_show rec loop_highlight (x : int) : int =
   let z : int = (x - 1) / 2 in
   if x <= 0 then 0 else z + loop_highlight (z + (x / 2))
 let () = print_endline @@ Int.to_string @@ loop_highlight 7
@@ -191,14 +191,14 @@ Example showcasing the `printbox-md` (Markdown) backend:
 
 ## Usage
 
-Tracing only happens in explicitly marked lexical scopes. The entry extension points vary along four axes:
+Tracing only happens in explicitly marked lexical scopes. For extension points applied directly to bindings (let-definitions) only the `let` definition in scope for logging, the body of the definition(s) is considered outside the extension point. (But if the extension is over an expression with a nested let-binding, the body of the definition is in the scope of the extension.)
+
+The entry extension points vary along three axes:
 
 - `%debug_` vs. `%track_` vs. `%diagn_`
   - The prefix `%debug_` means logging fewer things: only let-bound values and functions are logged, and functions only when either: directly in a `%debug_`-annotated let binding, or their return type is annotated.
   - `%track_` also logs: which `if`, `match`, `function` branch is taken, `for` and `while` loops, and all functions, including anonymous ones.
   - The prefix `%diagn_` means only generating logs for explicitly logged values, i.e. introduced by `[%log_entry]`, `[%log ...]`, `[%log_result ...]` and `[%log_printbox ...]` statements.
-- Optional infix `_this_` puts only the body of a `let` definition in scope for logging.
-  - `let%debug_this_show v: t = compute value in outer scope` will trace `v` and the type-annotated bindings and functions inside `compute value`, but it will not trace `outer scope`.
 - Optional infixes `_rt_` and `_rtb_` add a first-class module argument to a function, and unpack it as `module Debug_runtime` for the scope of the function.
   - `_rt_` uses the module type `Minidebug_runtime.Debug_runtime`.
   - `_rtb_` uses the module type `Minidebug_runtime.PrintBox_runtime`.
@@ -366,7 +366,7 @@ BEGIN DEBUG SESSION
 and
 
 ```ocaml
-  let%track_this_show anonymous (x : int) =
+  let%track_show anonymous (x : int) =
     Array.fold_left ( + ) 0 @@ Array.init (x + 1) (fun (i : int) -> i)
   in
   print_endline @@ Int.to_string @@ anonymous 3
@@ -554,7 +554,7 @@ Another example from the test suite:
       [%log1 "for bar, b-3", (b - 3 : int)];
       (b - 3) * y
     in
-    let%debug2_this_show baz { first : int; second : int } : int =
+    let%debug2_show baz { first : int; second : int } : int =
       let { first : int; second : int } = { first = first + 1; second = second + 3 } in
       [%log "for baz, f squared", (first * first : int)];
       (first * first) + second
@@ -786,7 +786,7 @@ In the PrintBox backend, you can disable the logging of specified subtrees, when
 The test suite example:
 
 ```ocaml
-  let%debug_this_show rec fixpoint_changes (x: int): int =
+  let%debug_show rec fixpoint_changes (x: int): int =
     let z: int = (x - 1) / 2 in
     (* The call [x = 2] is not printed because it is a descendant of
        the no-debug call [x = 4]. *)
@@ -823,7 +823,7 @@ Setting the option `truncate_children` will only log the given number of childre
 ```ocaml
   let module Debug_runtime = (val Minidebug_runtime.debug ~truncate_children:10 ()) in
   let () =
-    let%track_this_show _bar : unit =
+    let%track_show _bar : unit =
       for i = 0 to 30 do
         let _baz : int = i * 2 in
         ()
@@ -1277,7 +1277,7 @@ For programs with threads or domains running concurrently, you need to ensure th
 
 We offer three helpers for dealing with multiple debug runtimes. There is an optional runtime instance-level setting `global_prefix`, which adds the given information to all log headers coming from the instance.
 
-There are extension points `%debug_lb_sexp`, `%debug_this_lb_sexp`, `%track_lb_sexp`, etc. They call a function `_get_local_printbox_debug_runtime ()`, or `_get_local_debug_runtime ()` for the `_l_` variants, and unpack the argument as `module Debug_runtime` (in a function body). The feature helps using a runtime instance dedicated to a thread or domain, since for example `_get_local_debug_runtime` can retrieve the runtime using `Domain.DLS`. To avoid surprises, this feature only takes effect for directly annotated functions, and unpacks a `Debug_runtime` inside the function body (regardless of whether there is a `_this_`), so that we get the appropriate runtime for the dynamic local scope.
+There are extension points `%debug_lb_sexp`, `%track_lb_sexp`, `%debug_l_sexp`, etc. They call a function `_get_local_printbox_debug_runtime ()`, or `_get_local_debug_runtime ()` for the `_l_` variants, and unpack the argument as `module Debug_runtime` (in a function body). The feature helps using a runtime instance dedicated to a thread or domain, since for example `_get_local_debug_runtime` can retrieve the runtime using `Domain.DLS`. To avoid surprises, this feature only takes effect for directly annotated functions, and unpacks a `Debug_runtime` inside the function body, so that we get the appropriate runtime for the dynamic local scope.
 
 Example from the test suite:
 
@@ -1286,7 +1286,7 @@ Example from the test suite:
   let _get_local_debug_runtime () =
     Minidebug_runtime.debug_flushing ~global_prefix:("foo-" ^ string_of_int !i) ()
   in
-  let%track_this_l_show foo () =
+  let%track_l_show foo () =
     let () = () in
     ()
   in
@@ -1318,7 +1318,7 @@ Example from the test suite:
     |}]
 ```
 
-Another similar feature is the extension points `%debug_rtb_sexp`, `%debug_this_rtb_sexp`, `%track_rtb_sexp`, etc. They add a first-class module argument to a function, and unpack the argument as `module Debug_runtime`. At present, passing of the runtime instance to functions needs to be done manually. Note that only the function attached to the `_rt_` or `_rtb_` extension point is modified, regardless of whether there is a `_this_`.
+Another similar feature is the extension points `%debug_rtb_sexp`, `%track_rtb_sexp` `%debug_rt_sexp`, etc. They add a first-class module argument to a function, and unpack the argument as `module Debug_runtime`. At present, passing of the runtime instance to functions needs to be done manually. Note that only the function attached to the `_rt_` or `_rtb_` extension point is modified.
 
 Example from the test suite: