250612.1

graham-trott · graham-trott · commit 887d882853d8 · 2025-06-12T23:06:47.000+01:00
diff --git a/dist/easycoder-250612.1-py2.py3-none-any.whl b/dist/easycoder-250612.1-py2.py3-none-any.whl
diff --git a/dist/easycoder-250612.1.tar.gz b/dist/easycoder-250612.1.tar.gz
diff --git a/doc/core/README.md b/doc/core/README.md
@@ -10,7 +10,7 @@ There are three primary components to the language:
 
 The core keywords are:
 
-[add](keywords/add.md) [append](keywords/append.md) [assert](keywords/assert.md) [begin](keywords/begin.md) [clear](keywords/clear.md) [close](keywords/close.md) [create](keywords/create.md) [debug](keywords/debug.md) [decrement](keywords/decrement.md) [delete](keywords/delete.md) [divide](keywords/divide.md) [exit](keywords/exit.md) [file](keywords/file.md) [fork](keywords/fork.md) [get](keywords/get.md) [go](keywords/go.md) [gosub](keywords/gosub.md) [if](keywords/if.md) [import](keywords/import.md) [increment](keywords/increment.md) [index](keywords/index.md) [init](keywords/init.md) [input](keywords/input.md) [load](keywords/load.md) [lock](keywords/lock.md) [module](keywords/module.md) [multiply](keywords/multiply.md) [negate](keywords/negate.md) [open](keywords/open.md) [pop](keywords/pop.md) [post](keywords/post.md) [print](keywords/print.md) [push](keywords/push.md) [put](keywords/put.md) [read](keywords/read.md) [replace](keywords/replace.md) [return](keywords/return.md) [run](keywords/run.md) [save](keywords/save.md) [script](keywords/script.md) [set](keywords/set.md) [split](keywords/split.md) [stack](keywords/stack.md) [stop](keywords/stop.md) [system](keywords/system.md) [take](keywords/take.md) [toggle](keywords/toggle.md) [truncate](keywords/truncate.md) [unlock](keywords/unlock.md) [variable](keywords/variable.md) [wait](keywords/wait.md) [while](keywords/while.md) [write](keywords/write.md)
+[add](keywords/add.md) [append](keywords/append.md) [assert](keywords/assert.md) [begin](keywords/begin.md) [clear](keywords/clear.md) [close](keywords/close.md) [create](keywords/create.md) [debug](keywords/debug.md) [decrement](keywords/decrement.md) [delete](keywords/delete.md) [divide](keywords/divide.md) [exit](keywords/exit.md) [file](keywords/file.md) [fork](keywords/fork.md) [get](keywords/get.md) [go](keywords/go.md) [gosub](keywords/gosub.md) [if](keywords/if.md) [import](keywords/import.md) [increment](keywords/increment.md) [index](keywords/index.md) [init](keywords/init.md) [input](keywords/input.md) [load](keywords/load.md) [lock](keywords/lock.md) [log](keywords/log.md) [module](keywords/module.md) [multiply](keywords/multiply.md) [negate](keywords/negate.md) [on](keywords/on.md) [open](keywords/open.md) [pop](keywords/pop.md) [post](keywords/post.md) [print](keywords/print.md) [push](keywords/push.md) [put](keywords/put.md) [read](keywords/read.md) [release](keywords/release.md) [replace](keywords/replace.md) [return](keywords/return.md) [run](keywords/run.md) [save](keywords/save.md) [script](keywords/script.md) [send](keywords/send.md) [set](keywords/set.md) [shuffle](keywords/shuffle.md) [split](keywords/split.md) [stack](keywords/stack.md) [stop](keywords/stop.md) [system](keywords/system.md) [take](keywords/take.md) [toggle](keywords/toggle.md) [truncate](keywords/truncate.md) [unlock](keywords/unlock.md) [use](keywords/use.md) [variable](keywords/variable.md) [wait](keywords/wait.md) [while](keywords/while.md) [write](keywords/write.md)
 
 The core values are:
 
diff --git a/doc/core/keywords/negate.md b/doc/core/keywords/negate.md
@@ -7,7 +7,7 @@
 ## Description:
 Negates a numeric variable (multiplies its value by -1).
 
-Next: [open](open.md)  
+Next: [on](on.md)  
 Prev: [multiply](multiply.md)
 
 [Back](../../README.md)
diff --git a/doc/core/keywords/on.md b/doc/core/keywords/on.md
@@ -0,0 +1,14 @@
+# on
+
+## Syntax:
+`on message {action}`
+## Example:
+`on message go to HandleMessage`
+
+## Description:
+When another script uses `send {message} to {module}` (see [send](send.md)) to send this module a message (a text string), the message is saved and the designated `{action}` is invoked. The message text can be retrieved using `the message`.
+
+Next: [open](open.md)  
+Prev: [negate](negate.md)
+
+[Back](../../README.md)
diff --git a/doc/core/keywords/open.md b/doc/core/keywords/open.md
@@ -22,6 +22,6 @@
 Opens a disk file for reading, writing or appending. Each of the [file](file.md) variables must be declared as such as in the example.
 
 Next: [pop](pop.md)  
-Prev: [negate](negate.md)
+Prev: [on](on.md)
 
 [Back](../../README.md)
diff --git a/doc/core/keywords/release.md b/doc/core/keywords/release.md
@@ -9,7 +9,7 @@
 ## Description:
 Release the parent script. When a child module is run it blocks the parent from running until either it exits or it issues the `release parent` command. This allows it to do initialisation that cannot be interrupted but which may involve timed delays.
 
-Next: [multiply](multiply.md)  
-Prev: [lock](lock.md)
+Next: [replace](replace.md)  
+Prev: [read](read.md)
 
 [Back](../../README.md)
diff --git a/doc/core/keywords/script.md b/doc/core/keywords/script.md
@@ -8,7 +8,7 @@
 ## Description:
 Provides a name for the script. Note that `name` is literal text, not a script variable.
 
-Next: [set](set.md)  
+Next: [send](send.md)  
 Prev: [save](save.md)
 
 [Back](../../README.md)
diff --git a/doc/core/keywords/send.md b/doc/core/keywords/send.md
@@ -0,0 +1,14 @@
+# send
+
+## Syntax:
+`send {message} to {module}`
+## Examples:
+``send `No errors` to Main``
+
+## Description:
+Sends a message to another script. See [on message](on.md).
+
+Next: [set](set.md)  
+Prev: [script](script.md)
+
+[Back](../../README.md)
diff --git a/doc/core/keywords/set.md b/doc/core/keywords/set.md
@@ -25,7 +25,7 @@
 
 -- Sets the encoding to be used by the [encode](../values/encode.md) and [decode](../values/decode.md) value handlers. The encoder options are `utf-8` and `base64`. The default is `utf-8` if none is set by the script.
 
-Next: [split](split.md)  
-Prev: [script](script.md)
+Next: [shuffle](shuffle.md)  
+Prev: [send](send.md)
 
 [Back](../../README.md)
diff --git a/doc/core/keywords/shuffle.md b/doc/core/keywords/shuffle.md
@@ -0,0 +1,18 @@
+# shuffle
+
+## Syntax:
+`shuffle {variable}`
+
+## Example:
+`shuffle MyList`
+
+## Description:
+Shuffles (reorders randomly) the contents of the named array.
+EasyCoder has two array mechanisms. One is to hold a single value comprising a list of items (typically expressed as a JSON list). This is the type that can be shuffled with this command.
+
+The second mechanism is where any variable can have multiple elements, an internal `index` variable specifying which element is pointed to. This kind of array always acts like a single value, and cannot be shuffled. See [set the elements of](set.md).
+
+Next: [split](split.md)  
+Prev: [set](set.md)
+
+[Back](../../README.md)
diff --git a/doc/core/keywords/split.md b/doc/core/keywords/split.md
@@ -10,6 +10,6 @@
 Split a [variable](variable.md) containing a string into a number of parts on a given delimiter. The command sizes the variable to have as many elements as there are parts in the split string, and puts one part in each element.
 
 Next: [stack](stack.md)  
-Prev: [set](set.md)
+Prev: [shuffle](shuffle.md)
 
 [Back](../../README.md)
diff --git a/doc/core/keywords/unlock.md b/doc/core/keywords/unlock.md
@@ -1,4 +1,4 @@
-# ulock
+# unlock
 
 ## Syntax:
 `unlock {variable}`
@@ -9,7 +9,7 @@
 ## Description:
 Unlocks a locked variable to allow it to be modified. See also [lock](lock.md).
 
-Next: [lock](lock.md)  
-Prev: [init](init.md)
+Next: [use](use.md)  
+Prev: [truncate](truncate.md)
 
 [Back](../../README.md)
diff --git a/doc/core/keywords/use.md b/doc/core/keywords/use.md
@@ -0,0 +1,17 @@
+# use
+
+## Syntax:
+`use {feature}`
+
+## Examples:
+`use graphics`
+
+## Description:
+This is a special directive that calls in special functionality that is a standard part of EasyCoder but not included in all cases. The only one currently available is `graphics`, which is not included automatically because some systems don't have a graphical interface. The new functionality extends the language to deal with the specific feature.
+
+The `use` directive must always be placed at the top of a script, before any of its features have been called for.
+
+Next: [variable](variable.md)  
+Prev: [unlock](unlock.md)
+
+[Back](../../README.md)
diff --git a/doc/core/keywords/variable.md b/doc/core/keywords/variable.md
@@ -12,6 +12,6 @@ Declare a variable - an arbitrary storage item. Variables may hold string, numer
 Variables can be assigned any number of elements - see [set the elements](set.md). Each element can hold a data value of any of the 3 types above.
 
 Next: [wait](wait.md)  
-Prev: [unlock](toggle.md)
+Prev: [use](use.md)
 
 [Back](../../README.md)
diff --git a/easycoder/__init__.py b/easycoder/__init__.py
@@ -9,4 +9,4 @@
 from .ec_timestamp import *
 from .ec_value import *
 
-__version__ = "250611.6"
+__version__ = "250612.1"
diff --git a/easycoder/ec_core.py b/easycoder/ec_core.py
@@ -110,14 +110,6 @@ def r_append(self, command):
         self.putSymbolValue(target, val)
         return self.nextPC()
 
-    # Define an array
-    def k_array(self, command):
-        return self.compileVariable(command)
-
-    def r_array(self, command):
-        return self.nextPC()
-
-    # Assertion
     #assert {condition} [with {message}]
     def k_assert(self, command):
         command['test'] = self.nextCondition()
@@ -896,13 +888,6 @@ def r_negate(self, command):
         self.putSymbolValue(symbolRecord, value)
         return self.nextPC()
 
-    # Define an object variable
-    def k_object(self, command):
-        return self.compileVariable(command)
-
-    def r_object(self, command):
-        return self.nextPC()
-
     # on message {action}
     def k_on(self, command):
         if self.nextIs('message'):
@@ -1187,6 +1172,16 @@ def r_read(self, command):
             self.putSymbolValue(symbolRecord, value)
         return self.nextPC()
 
+    # Release the parent script
+    def k_release(self, command):
+        if self.nextIs('parent'):
+            self.add(command)
+        return True
+
+    def r_release(self, command):
+        self.program.releaseParent()
+        return self.nextPC()
+
     # Replace a substring
     #replace {value} with {value} in {variable}
     def k_replace(self, command):
@@ -1217,16 +1212,6 @@ def r_replace(self, command):
         self.putSymbolValue(templateRecord, value)
         return self.nextPC()
 
-    # Release the parent script
-    def k_release(self, command):
-        if self.nextIs('parent'):
-            self.add(command)
-        return True
-
-    def r_release(self, command):
-        self.program.releaseParent()
-        return self.nextPC()
-
     # Return from subroutine
     def k_return(self, command):
         self.add(command)
@@ -1281,11 +1266,6 @@ def r_run(self, command):
         p(path).start(parent, module, exports)
         return 0
 
-    # Provide a name for the script
-    def k_script(self, command):
-        self.program.name = self.nextToken()
-        return True
-
     # Save a value to a file
     def k_save(self, command):
         command['content'] = self.nextValue()
@@ -1350,6 +1330,11 @@ def r_save(self, command):
                 RuntimeError(self.program, f'Error: {errorReason}')
         return self.nextPC()
 
+    # Provide a name for the script
+    def k_script(self, command):
+        self.program.name = self.nextToken()
+        return True
+
     # Send a message to a module
     def k_send(self, command):
         command['message'] = self.nextValue()
