Des menus dans votre terminal - retour accueil
git clone git://bebou.netlib.re/zenu
Log | Files | Refs | README |
README (4117B)
1 # A CLI menu engine in ZSH
2
3 Written by Marc Chantreux
4
5 ## How to install
6
7 Zenu requires at least zsh and GNU sed to work.
8
9 First, source the ZSH functions written in zenu.zsh in your `.zshrc` file
10
11 echo ". path/to/zenu/zenu.zsh" >> path/to/.zshrc
12
13 Then provide menu files in a `menus` folder found at the root of this git
14 project. Create it if it doesn't exist. Examples given in the `eg` folder can
15 be copied to `menus`.
16
17 Build the script files
18
19 make
20
21 And launch the loop
22
23 zenu.loop in path/to/zenu/menus
24
25 If you used the examples given in `eg` you should see
26
27 mail
28 recent (MRU)
29 jobs
30 notes
31 network
32
33 With some letters highlighted.
34
35 You can make the command `zenu.loop in path/to/zenu/menus` easily accessible
36 in you `.zshrc` file :
37
38 # With a shortcut (ctrl+w)
39 bindkey -s '' 'zenu.loop in path/to/zenu/menus'
40 # With an alias
41 alias z="zenu.loop in path/to/zenu/menus"
42
43 ## Usage
44
45 To enter submenus and/or execute commands, use the highlighted key. By default
46 to go back one menu press enter.
47
48 ### Creating / Customizing menus
49
50 Menus are stored in the `menus` folder. The file named `main` is the default
51 starting menu. A menu is defined as
52
53 1. A list of commands and/or submenus with one given key being its activator
54
55 This part of the main menu given as an example looks like :
56
57 mail
58 recent (MRU)
59 jobs
60 notes
61 net work
62
63 by default the character preceding the activator key has to be `ctrl+_` : ` `.
64
65 2. An optional "pre" section
66
67 This section is arbitrary zsh code executed before zenu listens for a key
68 press. It can be used to make the following section easier to write or print
69 information below the menu section. By default this section starts after a `##
70 pre` comment in our menu declaration.
71
72 In the `network` menu given as an example in the `eg` folder this section the
73 pre section is as follows :
74
75 ## pre
76 local save=$zenu_store/network_interface
77 local state=$zenu_store/network_state
78 local nif=
79 touch $save
80 read nif < $save
81 echo
82 ip -br a | sed -r "
83 s/ /! / # separator for pick
84 s/^/ / # margin
85 "| tee $state |
86 sed "/${nif:-é}!/s/.*/\x1b[7m&\x1b[m/;s/!/ /"
87
88 Which (at least on my machine) prints basic information about the machines
89 network interfaces. This could also by a simple heredoc to document key
90 shortcuts or what each command does.
91
92 3. A scripting "react" section
93
94 This section is where you declare what each command should do. It starts with a
95 `## react` command and follows the zsh `case` syntax.
96
97 The react section of the main menu in the eg folder :
98
99 ## react
100 ;; (m) zenu+ mail
101 ;; (r) zenu+ mru
102 ;; (w) zenu+ network
103 ;; (n) vim ~p/start +'cd %:h' +'setf roguemode'
104
105 The line should always start with `;;`. The letter between brackets should
106 match with the corresponding activator key in the first section. In the first
107 section the "m" key was identified as activating the `mail` command therefore
108 corresponding reaction should be `;; (m) command`.
109
110 What comes after the activation key is arbitrary zsh code. If a submenu is to be
111 opened the `zenu+` function, written in `zenu.zsh` can be used with the name of
112 the submenu passed as an argument. For it to work the given argument has to exist
113 as a menu file in `menus`.
114
115 The entire main menu file with an added small tutorial would be :
116
117 mail
118 recent (MRU)
119 jobs
120 notes
121 net work
122 ## pre
123 <<% cat
124 Welcome to your menu
125 Press the highlighted keys to navigate and enter to go back up one menu
126 %
127 ## react
128 ;; (m) zenu+ mail
129 ;; (r) zenu+ mru
130 ;; (w) zenu+ network
131 ;; (n) vim ~p/start +'cd %:h' +'setf roguemode'
132
133 ### Changing defaults
134
135 #### "Go up a menu" key
136
137 To modify the default "go up a menu" key from enter to something else edit the
138 case around line 26 of `bin/build`.
139
140 For example, to substitute enter for both backspace and `q`
141
142 ...
143 case "\$zenu_key"
144 in (\$'') zenu--
145 ;; (\$'q') zenu--
146 ...
147
148 #### Activator key declarator
149
150 To modify which character has to precede the activator key for a command from
151 ctrl+_ to something else
152
153 #### Default starting menu
154
155 To modify the default starting menu from main to another file modify line 36 of
156 zenu.zsh
157
158 zenu_stack=( anotherfile )