move around a bunch of the files that aren't actually in use

to better describe their status

Force-Push: yes
Change-Id: If5ef70b7872700ff36ef07f20aac1f3b991dff45

1 files changed, 74 insertions, 0 deletions

diff --git a/experiments/mutable-modules.e b/experiments/mutable-modules.e
new file mode 100644
index 0000000..5180e4d
--- /dev/null
+++ b/experiments/mutable-modules.e
@@ -0,0 +1,74 @@
+~ 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
+