From f1a52b71ac5e6bc0e7de0cdbc2cb4751cddd9a60 Mon Sep 17 00:00:00 2001
From: crc <>
Date: Tue, 21 Nov 2023 14:49:38 +0000
Subject: [PATCH] add a new example showing a limited form of vocabulary

FossilOrigin-Name: 4ffa02ea0bd8f8aef134a60af926608ee2342e90496335bc9b8a90b5e60e61b4
---
 RELEASE-NOTES            |  1 +
 example/vocabulary.retro | 56 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 example/vocabulary.retro

diff --git a/RELEASE-NOTES b/RELEASE-NOTES
index 0cd505b..27f16c2 100644
--- a/RELEASE-NOTES
+++ b/RELEASE-NOTES
@@ -47,5 +47,6 @@
 - use mode array instead of conditionals when opening files and
   pipes
 - remove unused files from vm/nga-c
+- new example: vocabulary.retro
 
 ================================================================
diff --git a/example/vocabulary.retro b/example/vocabulary.retro
new file mode 100644
index 0000000..ceefe14
--- /dev/null
+++ b/example/vocabulary.retro
@@ -0,0 +1,56 @@
+# An Experiment in Vocabularies
+
+Retro provides a single dictionary. By convention, we use short
+prefixes for namespaces  and have some limited ability  to hide
+definitions  using `{{`,  `---reveal---`,  and  `}}`.  But it's
+sometimes  nice to be  able to hide words  and reveal them only
+when actually needed.
+
+These  words  provide a minimal  form of vocabulary by allowing
+temporarily relinking the main dictionary to follow a different
+path. The idea is to provide a word that points to a data stru-
+cture with the current Dictonary pointer. When in use, the main
+Dictionary is  relinked  to this,  and when closed,  the stored
+pointer is updated.
+
+~~~
+{{
+  'a var  'b var
+---reveal---
+  :forth (-) @b @a @Dictionary swap store !Dictionary ;
+  :with (a-) @Dictionary swap dup fetch !Dictionary !a !b ;
+  :voc  (s-) d:create @Dictionary comma ;
+}}
+~~~
+
+# Some Tests
+
+```
+:a #3 n:put nl ;
+:b #5 n:put nl ;
+a  b
+
+'test voc &test with
+  :a #1 n:put nl ;
+  :b #2 n:put nl ;
+a  b
+
+forth
+a  b
+&test
+:b #7 n:put nl ;
+a b
+&test with
+a b
+forth
+'foo voc &foo with
+:b #9 n:put nl ;
+a b
+forth
+
+a b
+&test with a b :c #100 n:put nl ; c forth
+c
+&foo with c forth
+&test with c forth
+```