zenu

git clone git://bebou.netlib.re/zenu
Log | Files | Refs |

commit a687ed79304fb7b003112aab32449d5cdb131e69
parent 2e83620543e844bb24ede340536e8b18a379d7e9
Auterice: arthur <arthur.pons@unistra.fr>
Date:   Fri, 12 May 2023 14:23:56 +0200

Added README, bin/build as dependency in makefile

README should be reasonable (no 30 page essay)
bin/build can be modified to change default "go back" key
or highlighter tag so it should be a dependency

Diffstat:
M
.gitignore
 | 
3
++-
A
README
 | 
156
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
M
makefile
 | 
8
++++----

3 files changed, 162 insertions(+), 5 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -1 +1,2 @@
-menus/*.*
+menus/*
+*.swp
diff --git a/README b/README
@@ -0,0 +1,156 @@
+# A CLI menu engine in ZSH
+
+Written by Marc Chantreux
+
+## How to install
+
+First, source the ZSH functions written in zenu.zsh in your `.zshrc` file
+
+	echo ". path/to/zenu/zenu.zsh" >> path/to/.zshrc
+
+Then provide menu files in a `menus` folder found at the root of this git
+project. Create it if it doesn't exist. Examples given in the `eg` folder can
+be copied to `menus`.
+
+Build the script files
+
+	make
+
+And launch the loop
+
+	zenu.loop in path/to/zenu/menus
+
+If you used the examples given in `eg` you should see
+
+	 mail
+	 recent (MRU)
+	 jobs
+	 notes
+	 network
+
+With some letters highlighted.
+
+You can make the command `zenu.loop in path/to/zenu/menus` easily accessible
+in you `.zshrc` file :
+
+	# With a shortcut (ctrl+w)
+	bindkey -s '' 'zenu.loop in path/to/zenu/menus'
+	# With an alias
+	alias z="zenu.loop in path/to/zenu/menus"
+
+## Usage
+
+To enter submenus and/or execute commands, use the highlighted key. By default
+to go back one menu press enter.
+
+### Creating / Customizing menus
+
+Menus are stored in the `menus` folder. The file named `main` is the default
+starting menu. A menu is defined as
+
+  1. A list of commands and/or submenus with one given key being its activator
+
+This part of the main menu given as an example looks like :
+
+	mail
+	recent (MRU)
+	jobs
+	notes
+	network
+
+by default the character preceding the activator key has to be `ctrl+_` : ``.
+
+  2. An optional "pre" section
+
+This section is arbitrary zsh code executed before zenu listens for a key
+press. It can be used to make the following section easier to write or print
+information below the menu section. By default this section starts after a `##
+pre` comment in our menu declaration.
+
+In the `network` menu given as an example in the `eg` folder this section the
+pre section is as follows :
+
+	## pre
+	local save=$zenu_store/network_interface
+	local state=$zenu_store/network_state
+	local nif=
+	touch $save
+	read nif < $save
+	echo
+	ip -br a | sed -r "
+		s/ /! /   # separator for pick
+		s/^/   /  # margin
+	"| tee $state |
+	sed "/${nif:-é}!/s/.*/\x1b[7m&\x1b[m/;s/!/ /"
+
+Which (at least on my machine) prints basic information about the machines
+network interfaces. This could also by a simple heredoc to document key
+shortcuts or what each command does.
+
+  3. A scripting "react" section
+
+This section is where you declare what each command should do. It starts with a
+`## react` command and follows the zsh `case` syntax.
+
+The react section of the main menu in the eg folder :
+
+	## react
+	;; (m) zenu+ mail
+	;; (r) zenu+ mru
+	;; (w) zenu+ network
+	;; (n) vim ~p/start +'cd %:h' +'setf roguemode'
+
+The line should always start with `;;`. The letter between brackets should
+match with the corresponding activator key in the first section. In the first
+section the "m" key was identified as activating the `mail` command therefore
+corresponding reaction should be `;; (m) command`.
+
+What comes after the activation key is arbitrary zsh code. If a submenu is to be
+opened the `zenu+` function, written in `zenu.zsh` can be used with the name of
+the submenu passed as an argument. For it to work the given argument has to exist
+as a menu file in `menus`.
+
+The entire main menu file with an added small tutorial would be :
+
+	mail
+	recent (MRU)
+	jobs
+	notes
+	network
+	## pre
+	<<% cat
+	Welcome to your menu
+	Press the highlighted keys to navigate and enter to go back up one menu
+	%
+	## react
+	;; (m) zenu+ mail
+	;; (r) zenu+ mru
+	;; (w) zenu+ network
+	;; (n) vim ~p/start +'cd %:h' +'setf roguemode'
+
+### Changing defaults
+
+#### "Go up a menu" key
+
+To modify the default "go up a menu" key from enter to something else edit the
+case around line 26 of `bin/build`.
+
+For example, to substitute enter for both backspace and `q`
+
+	...
+	case "\$zenu_key"
+	in (\$'') zenu--
+	;; (\$'q') zenu--
+	...
+
+#### Activator key declarator
+
+To modify which character has to precede the activator key for a command from
+ctrl+_ to something else
+
+#### Default starting menu
+
+To modify the default starting menu from main to another file modify line 36 of
+zenu.zsh
+
+	zenu_stack=( anotherfile )
diff --git a/makefile b/makefile
@@ -10,7 +10,7 @@ until    = ${to}/until.txt
 
 all: ${until} ${script} ${emph}
 
-${to}/%.face   : ${from}/%          ; bin/build -f $< > $@
-${to}/%.script : ${from}/% ${until} ; bin/build -s $< > $@
-${to}/%.emph   : ${from}/% ${until} ; bin/build -e $< > $@
-${until}       : ${face}            ; wc $? | awk 'n>m{m=n}{n=$$1}END{print m}' > $@
+${to}/%.face   : ${from}/%          bin/build ; bin/build -f $< > $@
+${to}/%.script : ${from}/% ${until} bin/build ; bin/build -s $< > $@
+${to}/%.emph   : ${from}/% ${until} bin/build ; bin/build -e $< > $@
+${until}       : ${face} ; wc $? | awk 'n>m{m=n}{n=$$1}END{print m}' > $@