From c87587d426462fed9afeabfb7c72df1b6ee8a1b7 Mon Sep 17 00:00:00 2001
From: Peter Hinch <peter@hinch.me.uk>
Date: Sat, 27 Feb 2021 18:05:53 +0000
Subject: [PATCH] Add notes on rshell macros.

---
 README.md        |  4 ++-
 RSHELL_MACROS.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 RSHELL_MACROS.md

diff --git a/README.md b/README.md
index df6a533..e2df37f 100644
--- a/README.md
+++ b/README.md
@@ -423,7 +423,9 @@ of required frequency response to a filter implementation.
 
 [rshell](https://github.com/peterhinch/rshell) is a fork of Dave Hylands'
 excellent utility. My fork adds text macros to improve its power and
-usability, notably when maintaining complex Python packages.  
+usability, notably when maintaining complex Python packages. The fork includes
+documentation, but [these notes](./RSHELL_MACROS.md) provide a usage example
+where each project has its own set of automatically loaded macros.__
 
 ## 5.10 Hard to categorise
 
diff --git a/RSHELL_MACROS.md b/RSHELL_MACROS.md
new file mode 100644
index 0000000..2c9fec8
--- /dev/null
+++ b/RSHELL_MACROS.md
@@ -0,0 +1,65 @@
+# The rshell macro fork
+
+These notes describe one of a number of possible ways to use the macro
+facility.
+
+The aim was to provide a set of generic macros, along with a project specific
+set. The starting point is an alias, run before work is started on a given
+project. The aliases are created in `~/.bashrc`. The example below is for two
+projects, `mqtt` and `asyn`.
+```bash
+alias asyn='export PROJECT=ASYN;cd /MicroPython/micropython-async/'
+alias mqtt='export PROJECT=MQTT; cd /MicroPython/micropython-mqtt'
+```
+The `PROJECT` environment variable is examined by the file `rshell_macros.py`
+located in the `rshell` directory. An example is presented here:
+```python
+import os
+proj = None
+try:
+    proj = os.environ['PROJECT']
+except KeyError:
+    print('Environment var PROJECT not found: only generic macros loaded.')
+
+macros = {}
+macros['..'] = 'cd ..'
+macros['...'] = 'cd ../..'
+macros['ll'] = 'ls -al {}', 'List any directory'
+macros['lf'] = 'ls -al /flash/{}'
+macros['lsd'] = 'ls -al /sd/{}'
+macros['lpb'] = 'ls -al /pyboard/{}'
+macros['mv'] = 'cp {0} {1}; rm {0}', 'Move/rename'
+macros['repl'] = 'repl ~ import machine ~ machine.soft_reset()', 'Clean REPL'
+macros['up'] = 'cd /MicroPython'
+macros['asyn'] = 'cd /MicroPython/micropython-async'
+macros['primitives'] = 'cd /MicroPython/micropython-async/v3; rsync primitives/ {}/primitives; cd -', 'Copy V3 primitives to dest'
+
+if proj == 'MQTT':
+    print('Importing macros for MQTT')
+    macros['home'] = 'cd /MicroPython/micropython-mqtt/mqtt_as'
+elif proj == 'ASYN':
+    print('Importing macros for ASYN')
+    macros['home'] = 'cd /MicroPython/micropython-async'
+    macros['v3'] = 'cd /MicroPython/micropython-async/v3'
+    macros['off'] = 'cd /MicroPython/micropython-async/official', 'official uasyncio'
+    macros['sync'] = 'cd /MicroPython/micropython-async/v3; rsync primitives/ {}/primitives', 'Copy V3 primitives to dest'
+    macros['demos'] = 'cd /MicroPython/micropython-async/v3; rsync as_demos/ {}/as_demos', 'Copy V3 demos to dest'
+    macros['drivers'] = 'cd /MicroPython/micropython-async/v3; rsync as_drivers/ {}/as_drivers', 'Copy V3 drivers to dest'
+```
+The first part of the script defines generic macros such as `ll` and `lsd`
+available to any project, and if no project is defined.
+
+Project specific macros are added in response to the environment variable.
+Note the way args are passed: to update the SD card on a Pyboard the macro
+`primitives` would be called with:
+```
+MicroPython > m primitives /sd
+```
+The `mv` macro, called with
+```
+MicroPython > m mv source_path dest_path
+```
+expands to
+```
+cp source_path dest_path; rm source_path
+```