Library
Module
Module type
Parameter
Class
Class type
The signature of scoping effects.
module Param : sig ... end
A scope inherently has two namespaces: a visible namespace that dictates what's visible, and an export namespace recording all the names that will be exported.
type not_found_handler = Param.context option -> Trie.bwd_path -> unit
The type of a handler of the Modifier.S.Perform.not_found
effect.
type shadow_handler =
Param.context option ->
Trie.bwd_path ->
(Param.data * Param.tag) ->
(Param.data * Param.tag) ->
Param.data * Param.tag
The type of a handler of the Modifier.S.Perform.shadow
effect.
type hook_handler =
Param.context option ->
Trie.bwd_path ->
Param.hook ->
(Param.data, Param.tag) Trie.t ->
(Param.data, Param.tag) Trie.t
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.
val resolve : Trie.path -> (Param.data * Param.tag) option
resolve p
looks up the name p
in the visible namespace and returns the data associated with the binding.
Inclusion affects both visible and export namespaces, just like include
in OCaml.
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
. 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
.
val include_subtree :
?context_modifier:Param.context ->
?context_visible:Param.context ->
?context_export:Param.context ->
?modifier:Param.hook Language.t ->
(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
.
This feature is useful for introducing multiple top-level definitions at once.
Importing affects only the visible namespace, just like open
in OCaml.
val import_singleton :
?context_visible:Param.context ->
(Trie.path * (Param.data * Param.tag)) ->
unit
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] *)
val import_subtree :
?context_modifier:Param.context ->
?context_visible:Param.context ->
?modifier:Param.hook Language.t ->
(Trie.path * (Param.data, Param.tag) Trie.t) ->
unit
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
.
val modify_visible :
?context_visible: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.
When implementing an OCaml-like language, one can implement open M
as follows:
modify_visible Language.(union [seq []; only ["M"]])
When implementing an OCaml-like language, one can implement include M
as follows:
export_visible Language.(only ["M"]);
modify_visible Language.(union [seq []; only ["M"]])
val modify_export :
?context_export: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.
val export_visible :
?context_modifier:Param.context ->
?context_export: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
.
This feature is useful for implementing a userspace export
statement. It does not exist in OCaml-like languages.
val get_export : unit -> (Param.data, Param.tag) Trie.t
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).
val section :
?context_modifier:Param.context ->
?context_visible:Param.context ->
?context_export:Param.context ->
?modifier:Param.hook Language.t ->
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.
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
module type Perform = sig ... end
The signature of a module implementing all effect handlers for a lexical scope.
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.
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 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.