package yuujinchou

  1. Overview
  2. Docs

The signature of scoping effects.

module Param : sig ... end
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
exception Locked

The exception Locked is raised when an operation on a scope starts before another operation on the same scope is finished. This could happen when the user, for example, calls modify_visible and then calls modify_export when handling the effects.

The principle is that one should not access any scope in its intermediate states, including looking up a name via resolve. Any attempt to do so will raise the exception Locked.

Note: section only locks the parent scope; the child scope is initially unlocked.

Basics

val resolve : Trie.path -> (Param.data * Param.tag) option

resolve p looks up the name p in the current scope and return the data associated with the binding.

val include_singleton : ?context_visible:Param.context -> ?context_export:Param.context -> (Trie.path * (Param.data * Param.tag)) -> unit

include_singleton (p, x) adds a new binding to both the visible and export namespaces, where the binding is associating the data x to the path p. Conflicting names during the final merge will trigger the effect shadow.

  • parameter context_visible

    The context attached to the modifier effects when manipulating the visible namespace.

  • parameter context_export

    The context attached to the modifier effects when manipulating the export namespace.

val include_subtree : ?context_visible:Param.context -> ?context_export:Param.context -> (Trie.path * (Param.data, Param.tag) Trie.t) -> unit

include_subtree (p, ns) merges the namespace ns prefixed with p into both the visible and export namespaces. Conflicting names during the final merge will trigger the effect shadow.

  • parameter context_visible

    The context attached to the modifier effects when manipulating the visible namespace.

  • parameter context_export

    The context attached to the modifier effects when manipulating the export namespace.

val import_subtree : ?context:Param.context -> (Trie.path * (Param.data, Param.tag) Trie.t) -> unit

include_subtree (p, ns) merges the namespace ns prefixed with p into the visible namespace (while keeping the export namespace intact). Conflicting names during the final merge will trigger the effect Mod.Shadowing.

  • parameter context

    The context attached to the modifier effects.

val modify_visible : ?context:Param.context -> Param.hook Language.t -> unit

modify_visible m modifies the visible namespace by running the modifier m on it, using the internal modifier engine.

  • parameter context

    The context attached to the modifier effects.

val modify_export : ?context:Param.context -> Param.hook Language.t -> unit

modify_visible m modifies the export namespace by running the modifier m on it, using the internal modifier engine.

  • parameter context

    The context attached to the modifier effects.

Call the internal modifier engine directly on some trie. See Yuujinchou.Modifier.S.modify.

This will not lock the current scope.

val export_visible : ?context:Param.context -> Param.hook Language.t -> unit

export_visible m runs the modifier m on the visible namespace, and then merge the result into the export namespace. Conflicting names during the final merge will trigger the effect Mod.Shadowing.

  • parameter context

    The context attached to the modifier effects.

val get_export : unit -> (Param.data, Param.tag) Trie.t

get_export () returns the export namespace of the current scope.

Sections

val section : ?context_visible:Param.context -> ?context_export:Param.context -> Trie.path -> (unit -> 'a) -> 'a

section p f starts a new scope and runs the thunk f within the scope. The child scope inherits the visible namespace from the parent, and its export namespace will be prefixed with p and merged into both the visible and export namespaces of the parent scope.

  • parameter context_visible

    The context attached to the modifier effects when merging the content of the section into its parent's visible namespace.

  • parameter context_export

    The context attached to the modifier effects when merging the content of the section into its parent's export namespace.

Runners

val run : ?not_found:not_found_handler -> ?shadow:shadow_handler -> ?hook:hook_handler -> ?export_prefix:Trie.bwd_path -> ?init_visible:(Param.data, Param.tag) Trie.t -> (unit -> 'a) -> 'a

run ~not_found ~shadow ~hook f initializes a scope and executes the thunk f, using h to handle modifier effects.

  • parameter export_prefix

    The additional global prefix prepended to the paths reported to effect handlers originating from export namespaces. The default is the empty path (Emp). This does not affect paths originating from visible namespaces.

  • parameter init_visible

    The initial visible namespace. The default is the empty trie.

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

Execute the code and handles the internal modifier effects.

try_with is intended to be used within run to intercept or reperform internal effects, while run is intended to be at the top-level to set up the environment and handle all effects by itself. For example, the following function silences the shadow effects, but the silencing function should be used within the dynamic scope of a run. See also Yuujinchou.Modifier.S.try_with.

let silence_shadow f =
  try_with ~shadow:Silence.shadow f

A consequence of the semantic difference between run and try_with is that run starts a fresh empty scope while try_with stays in the current scope.

module type Perform = sig ... end
module Perform : Perform
module Silence : Perform
OCaml

Innovation. Community. Security.