yuujinchou 4.0.0 · OCaml Package

The signature of the engine.

module Param : sig ... end

module type Perform = sig ... end

module Perform : Perform

module Silence : Perform

type not_found_handler = Param.context option -> Trie.bwd_path -> unit

type shadow_handler =
  Param.context option ->
  Trie.bwd_path ->
  (Param.data * Param.tag) ->
  (Param.data * Param.tag) ->
  Param.data * Param.tag

type hook_handler =
  Param.context option ->
  Trie.bwd_path ->
  Param.hook ->
  (Param.data, Param.tag) Trie.t ->
  (Param.data, Param.tag) Trie.t

val modify : 
  ?context:Param.context ->
  ?prefix:Trie.bwd_path ->
  Param.hook Language.t ->
  (Param.data, Param.tag) Trie.t ->
  (Param.data, Param.tag) Trie.t

modify modifier trie runs the modifier on the trie and return the transformed trie.

parameter context
The context sent to the effect handlers. If unspecified, effects come with None as their context.

parameter prefix
The prefix prepended to any path or prefix sent to the effect handlers. The default is the empty path (Emp).

val run : 
  ?not_found:not_found_handler ->
  ?shadow:shadow_handler ->
  ?hook:hook_handler ->
  (unit -> 'a) ->
  'a

run f initializes the engine and runs the thunk f.

parameter not_found
not_found ctx prefix is called when the engine expects at least one binding within the subtree at prefix but could not find any, where ctx is the context passed to S.modify. Modifiers such as Language.any, Language.only, Language.none, and a few other modifiers expect at least one matching binding. For example, the modifier Language.except ["x"; "y"] expects that there was already something under the subtree at x.y. If there were actually no names with the prefix x.y, then the modifier will trigger this effect with prefix being Emp #< "x" #< "y". The default handler directly returns the ().

parameter shadow
shadow ctx path x y is called when item y is being assigned to path but x is already bound at path, where ctx is the context passed to S.modify. Modifiers such as Language.renaming and Language.union could lead to bindings having the same name, and when that happens, this function is called to resolve the conflicting bindings. The default handler directly returns the y, effectively silencing the effects.

parameter hook
hook prefix id input is called when processing the modifiers created by Language.hook, where ctx is the context passed to S.modify. When the engine encounters the modifier Language.hook id while handling the subtree input at prefix, it will call hook prefix id input and replace the existing subtree input with the return value. The default handler returns input, effective skipping the hooks.

val try_with : 
  ?not_found:not_found_handler ->
  ?shadow:shadow_handler ->
  ?hook:hook_handler ->
  (unit -> 'a) ->
  'a

try_with f runs the thunk f and intercepts modifier effects. See the documentation of run for the meaning of the optional effect interceptors; the difference is that the default interceptors reperform the intercepted modifier effects instead of silencing them.

try_with is intended to be used within run to intercept or reperform effects, while run is intended to be at the top-level to set up the environment and handle effects by itself. That is, the following is the expected program structure:

run ~not_found ~shadow ~hook @@ fun () ->
(* code *)
try_with ~not_found @@ fun () ->
(* more code *)
try_with ~shadow @@ fun () ->
(* even more code *)

package yuujinchou