~ STATUS OF THIS FILE
~ this is scrap being collected in one place, in case it ever becomes relevant
~ again. it likely won't. at one time, the thinking was that the
~ transformation system might be easier to develop with this module facility,
~ but that turned out not to be the case.


~ Modules and module contexts
~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
~
~   A module is a set of related words which are, normally, only visible to
~ each other. All the words defined as part of a module must be defined
~ together; you begin defining a module by invoking the word "module:"
~ followed by the module's name, and end by invoking "end-module". Words
~ created while defining a module are flagged as visible until "end-module" is
~ called, at which point their entries are edited in place to be marked as
~ hidden, which will prevent accidental references to them from outside the.
~ module.
~
~   Additionally, the module's name becomes a word which becomes visible
~ after end-module runs, and provides a way to call the otherwise-hidden words
~ within the module. When written as a word, the module's name is followed by
~ the name of a word to call, which it reads and looks up within the module.
~ The module-name word then either compiles or executes a call to the word
~ that's found, depending on the mode the interpreter is in.
~
~   Within a module, it is permissible to define "contextual" words. Whereas
~ any normal word in Evocation has a single interface, some specific
~ expectations for how the value stack looks when it's called and how that's
~ different after it returns, contextual words have one interface that applies
~ to calls from outside the module or from non-contextual words within the
~ module, and another interface that applies when they call each other within
~ the same module.
~
~ TODO and what are those interfaces?
~ WHAT ARE THOSE INTERFACES, Irenes?

here @ 0 , s" context-stack" variable

: module:
  word value@ create dropstring docol , make-module-header
  [ dup entry-to-execution-token , ] ;




module: amazing-transformation 8 2 * allocate ;

~ ( -- transformee pointer)
: transformee amazing-transformation @ ;
: transformation-mode amazing-transformation @ 8 + ;

: frob-transformee
  transformee @
  ~ ...
  transformee ! ;

~ no parameters
: transform-one
  ~ ... complex stuff here ...
  ;

~ (transformee -- transformee)
: transform
  8 2 * allocate amazing-transformation !
  transformee !
  { transform-one
    { transformee @ exit } if
  } forever ;

end-module

amazing-transformation transform