package yuujinchou

The type of a handler of the Modifier.S.Perform.not_found effect.

The type of a handler of the Modifier.S.Perform.shadow effect.

The type of a handler of the Modifier.S.Perform.hook effect.

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; the exception Locked signals a serious programming error.

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

resolve p looks up the name p in the visible namespace and returns the data associated with the binding.

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. include_singleton (p, x) is equivalent to include_subtree Trie.(singleton (p, x)), but potentially more efficient.

When implementing an OCaml-like language, this is how one can introduce a top-level definition let p = x.

• parameter context_visible

  The context of modifier effects when merging the subtree into the visible namespace.

• parameter context_export

  The context of modifier effects when merging the subtree into the export namespace.

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.

This feature is useful for introducing multiple top-level definitions at once.

• parameter context_modifier

  The context of modifier effects when applying modifier.

• parameter context_visible

  The context of modifier effects when merging the subtree into the visible namespace.

• parameter context_export

  The context of modifier effects when merging the subtree into the export namespace.

• parameter modifier

  The modifier applied to the subtree before importing it. The default value is Language.id.

import_singleton (p, x) adds a new binding to the visible namespace (while keeping the export namespace intact), where the binding is associating the data x to the path p. Conflicting names during the final merge will trigger the effect shadow. import_singleton (p, x) is equivalent to import_subtree Trie.(singleton (p, x)), but potentially more efficient.

When implementing an OCaml-like language, one can implement the local binding let p = x in e as follows:

section [] @@ fun () ->
import_singleton (p, x);
(* code for handling the expression [e] *)

• parameter context_visible

  The context of modifier effects when merging the subtree into the visible namespace.

• since 5.0.0

import_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.

When implementing an OCaml-like language, one can import content from other compilation units using import_subtree.

• parameter context_modifier

  The context of modifier effects when applying modifier.

• parameter context_visible

  The context of modifier effects when merging the subtree into the visible namespace.

• parameter modifier

  The modifier applied to the subtree before importing it. The default value is Language.id.

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

When implementing an OCaml-like language, one can implement open M as follows:

modify_visible Language.(union [id; renaming ["M"] []])

When implementing an OCaml-like language, one can implement include M as follows:

export_visible Language.(renaming ["M"] []);
modify_visible Language.(union [id; renaming ["M"] []])

• parameter context

  The context of modifier effects.

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

• parameter context_export

  The context of modifier effects.

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.

This feature is useful for implementing a userspace export statement. It does not exist in OCaml-like languages.

• parameter context_modifier

  The context of modifier effects when applying the modifier m.

• parameter context_export

  The context of modifier effects when merging the subtree into the export namespace.

get_visible () returns the visible namespace of the current scope.

This is useful for obtaining all visible names for auto-completion. It can also be used for checking whether a shadowed definition is still visible under another name. (However, scanning the entire visible namespace is expensive and should probably be avoided.)

• since 5.2.0

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

This is useful for obtaining all exported content when wrapping up a compilation unit. The section function internally calls get_export when wrapping up a child scope, but an implementer is expected to call get_export for the outermost scope. The outermost scope is special because it is the interface of the entire compilation unit and its ending often triggers special handling code (e.g., caching of declared names for faster scope checking).

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.

A section is similar to a section in Coq or a module in Agda (but not a module in OCaml). This can be used to implement local bindings as well; a local binding is a private definition in a section. For example, in an OCaml-like languages augmented with sections,

let y = let x = 1 in x

is equivalent to

section {
  private let x = 1
  let y = x
} // this section exports y but not x

• parameter context_modifier

  The context of modifier effects when applying modifier to the content of the section before the merging.

• parameter context_visible

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

• parameter context_export

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

• parameter modifier

  The modifier applied to the content of the section before the merging. The default value is Language.id.

The signature of a module implementing all effect handlers for a lexical scope.

The handlers that (re-)perform effects.

The handlers that silence effects. All the triggers actually do nothing.

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

• parameter not_found

  See Yuujinchou.Modifier.S.run for the explanation of this argument.

• parameter shadow

  See Yuujinchou.Modifier.S.run for the explanation of this argument.

• parameter hook

  See Yuujinchou.Modifier.S.run for the explanation of this argument.

• 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 namespace.

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 Mod.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.

register_printer f registers a printer p via Printexc.register_printer to convert unhandled internal effects into strings for the OCaml runtime system to display. See Yuujinchou.Modifier.S.register_printer.

• since 5.1.0