package yuujinchou

README.mkd

# Yuujinchou: Name Pattern Combinators

_Yuujinchou_ is an OCaml package of name patterns for implementing import statements. Please consult the [generated documentation](https://redprl.org/yuujinchou/yuujinchou/Yuujinchou) for more details.

## How to Use It

```ocaml
open Yuujinchou

module Data =
struct
  type t = int
  let equal n1 n2 = n1 = n2
  let merge ~rev_path x y =
    if equal x y then
      Result.ok x
    else
      Result.error @@ `Inconsistent (List.rev rev_path)
  let shadow ~rev_path:_ _x y = y
  let compare : t -> t -> int = compare
end

(** An environment is a mapping from paths to data. *)
type env = Data.t Trie.t

(** [remap pattern env] uses the [pattern] to massage
    the environment [env]. *)
let remap pattern env =
  let pp_path = function [] -> "(root)" | path -> String.concat "." path in
  match Action.run ~union:Data.merge pattern env with
  | Ok env -> env
  | Error (`Inconsistent path) ->
    failwith ("Inconsistent data assigned to the same path " ^ pp_path path)
  | Error (`BindingNotFound path) ->
    failwith ("Expected binding(s) not found within the subtree at " ^ pp_path path)

(** [import env pattern imported] imports the environment
    [imported] massaged by [pattern] into [env]. *)
let import env pattern imported =
  Trie.union Data.shadow env @@ remap pattern imported

module DataSet = Set.Make (Data)

(** [select env pattern] returns the set of matched data. *)
let select env pattern =
  DataSet.of_seq @@ Trie.to_seq_values @@ remap pattern env
```

## Installation

You need OCaml 4.08.0 or newer. The package is available on the OPAM repository:
```
opam install yuujinchou
```

You could also check out the source repository and install the latest version in development:
```
git clone https://github.com/RedPRL/yuujinchou.git
opam install ./yuujinchou
```