Context

  empty :: NameSymbol.T -> IO (T term ty sumRep)

empty creates a new context in the name-space you call it with (thus empty "Foo.Bar" makes a context with the nested module Bar in Foo).

The current module is then set to this name.

  lookup ::
    NameSymbol.T -> T term ty sumRep -> Maybe (From (Definition term ty sumRep))

  (!?) ::
    T term ty sumRep -> NameSymbol.T -> Maybe (From (Definition term ty sumRep))

looup looks up the given name-symbol according to the rules in the Symbol resolution section. !? is just flipped lookup.

  add ::
    NameSpace.From Symbol ->
    Definition term ty sumRep ->
    T term ty sumRep ->
    T term ty sumRep

add name def context adds name with the definition def to the current name-space of an existing context. The type NameSpace.From can either be Pub or Priv currently, stating how we want to add the definition to the current context.

As can be observed, we are adding a Symbol and not a NameSymbol, and so this primitive can't add name to a separate module. This should be changed in time.

  remove ::
    NameSpace.From Symbol ->
    T term ty sumRep ->
    T term ty sumRep

remove name context removes the name from the public or private name-space of the current name-space.

  inNameSpace :: NameSymbol.T -> T term ty sumRep -> Maybe (T term ty sumRep)

inNameSpace name context is the primitive way in which we change the current name-space. like lookup, we use the standard symbol resolution rule to determine which module we resolve to. If the module is not found, then we simply return Nothing. Also if the definition we land on is not a record/module, then likewise we also return Nothing. If all is successful, then we end up with a new context with a new current name-space.

  data Stage b
    = -- | 'Final' signifies the last symbol that we
      -- pursue in updating a structure
      Final b
    | -- | 'Continue' signifies that there are parts of
      -- the namespace that we can still continue down
      Continue b

  data Return term ty sumRep
    = -- | 'GoOn' signifies that we should continue
      -- going down records
      GoOn (Record term ty sumRep)
    | -- | 'Abort' signifies that we should cancel
      -- the changes on the map and
      Abort
    | -- | 'UpdateNow' signifies that we should
      -- update the context with the current value
      UpdateNow (Definition term ty sumRep)
    | -- | 'RemoveNow' signifies that we show remove
      -- the definition at this level
      RemoveNow

  modifySpaceImp ::
    Monad m =>
    ( Stage (Maybe (Definition term ty sumRep)) ->
      m (Return term ty sumRep)
    ) ->
    NameSymbol.T ->
    T term ty sumRep ->
    m (Maybe (T term ty sumRep))

modifySpaceImp f sym context is a rather important operation. Some forms like Empty even rely on it! modifySpaceImp is responsible for implementing the behavior for known symbols exactly how Symbol Resolution

lays it out, and for unknown symbols how Rules for Unresolved Symbols lays it out.

The Maybe it takes indicates whether the symbol is resolved or not.

We decided to include the Return and Stage type here, as they both talk about something integral to the design of this function. Namely the Return talks about the range of operations we care about. This limits the kinds of operations this modifyNameSpaceImp function can do. The Stage on the other hand denotes to the operation function f whether we are at the final symbol in the resolution or are we still going down to nested structure to find the proper symbol. Many operations will do something special at the very end, and so we often care about what stage we are at.

Finally, our function returns some monad m, this is due to just being general to accept any kind of function, as the name suggests there is a non Impure version of this, however this just runs this more general one in the Identity monad.

  switchNameSpace ::
    NameSymbol.T -> T term ty sumRep -> IO (Either PathError (T term ty sumRep))

switchNamespace name context is an important operation. This creates and switches to the name-space even if it doesn't exist! The rules for creation are exactly that ruled in the Symbol Resolution section.

The creation of new name-spaces are IO, and so the operation is in IO as well.