{0 yuujinchou: Hierarchical Names and Lexical Scoping}

{1 Introduction}

This library was motivated by the name modifiers in the "import" or "include" statements present in all practical programming languages.
Here are a few examples of such statements but without modifiers:

{v open import M -- Agda v}

{v import foo # Python v}

The ability to import content from other files helps organize code. However, it also poses a new challenge: how could programmers prevent imported content from shadowing existing content? For example, if we already have a function [test] in the current scope, maybe we do not wish to import another function also named [test]. To address this, many programming languages allow programmers to selectively hide or rename part of the imported content:

{v
open import M renaming (a to b) public
-- (Agda) renaming a to b, and then re-exporting the content
v}

Another way to address this is to place the imported content under some namespace. For example, in Python,

{v
import math # Python: the sqrt function is available as `math.sqrt`.
v}

Arguably, common designs of these hiding or renaming mechanisms are quite limited. The goal of the yuujinchou library is to provide a compositional calculus of these modifiers of names. Currently, the library supports renaming, scopes, sequencing, unions, and custom hooks for extending the engine.

{2 Lexical Scoping}

Later on, an implementation of lexical scoping based on name modifiers was added to the library. The implementation provides a flexible API for all common namespace operations ({i e.g.,} "import", "include", "open", sections, etc.). While it is still possible to use name modifiers without touching the code for the lexical scoping. Most language implementers would start with this newly added module. See {!module:Yuujinchou.Scope} for the API reference.

{1 More Information}

- {{!page:design}The design philosophy.} See also {{:https://youtu.be/5Cp8jNrWSjI}Favonia's TYPE 2022 talk}.
- {{:https://github.com/RedPRL/yuujinchou/blob/main/test/Example.ml}A tiny interpreter using yuujinchou} (available locally as [test/Example.ml]).
- {{!module:Yuujinchou}The API reference.}
- {{!page:rosetta}Implementing features in other languages.}

{1 What is "yuujinchou"?}

"yuujinchou" is the transliteration of "友人帳" in Japanese, which literally means "book of friends". It is a powerful notebook in the manga Natsume Yuujinchou (夏目友人帳) that collects many {e real names (真名)} of youkais (妖怪) (supernatural and spiritual monsters). These real names can be used to summon and control youkais, but the protagonist decided to return the names to their original owners. The plot is about meeting all kinds of youkais.

The magical notebook will automatically turn to the page with the correct name when the protagonist pictures the youkai in his mind. The earlier versions of this package focus on hierarchical names and name modifiers, which is about finding real names of youkais (the actual definitions). Later on, the package is extended with an implementation of lexical scoping.

Notes on the transliteration: "yuujinchou" is in the Wāpuro style so that it uses only the English alphabet; otherwise, its Hepburn romanization would be "Yūjin-chō".
