Merge pull request #6 from dwhinham/fish-completion

Add fish and zsh completion scripts and installation instructions in Readmes

README.md

@@ -18,6 +18,11 @@
   * [Atari ST](#atari-st)
   * [Linux](#linux)
   * [Windows](#windows)
+- [Installation](#installation)
+  * [Linux shell completion scripts](#linux-shell-completion-scripts)
+    + [bash completion script](#bash-completion-script)
+    + [fish completion script](#fish-completion-script)
+    + [zsh completion script](#zsh-completion-script)
 - [Showcase](#showcase)
 
 ## Features
@@ -30,6 +35,7 @@
 * DOS version compiled for 8086 Real Mode, so should work on pretty much any system with an MPU401-compatible interface
 * Amiga version is compiled for AmigaOS ≥1.3 and supports both `camd.library` and direct serial port access, so it likewise should work on pretty much any system
 * Useful for making game/application-specific start-up scripts to correctly set up the synth
+* NEW: Smart option autocompletion on Linux using the bash, fish, and zsh shells
 
 ## Usage Summary
 `MT32-PI.EXE`/`MT32-PI.TTP`/`mt32-pi-ctl` accept the following UNIX-style parameters:
@@ -80,11 +86,11 @@ OPTIONS:
 ```
 To find out which client/port to use, you can run `aplaymidi -l` or `aconnect -l` to list available devices.
 
-Since 1.0.1, the Linux version of `mt32-pi-ctl` also comes with an intelligent bash completion script
+Since 1.0.1a, the Linux version of `mt32-pi-ctl` also comes with intelligent bash, fish, and zsh completion scripts
 that will smartly autocomplete (long) options, romsets, filenames and, if `aplaymidi` is in your
 PATH, even available MIDI ports.
 
-Examples:
+Examples for bash:
 ```
 $ mt32-pi-ctl -p <TAB><TAB>
 14:0  28:0
@@ -98,20 +104,10 @@ $ mt32-pi-ctl -p 28:0 --romset <TAB><TAB>
 cm32l  new  old
 ```
 For this to work mt32-pi-ctl must be in your PATH, e.g. in `/usr/local/bin` and the
-bash completion script must be in a special completion script directory or sourced
+bash/fish completion scripts must be in a special completion script directory or for bash, sourced
-by `.bashrc`.
+by `.bashrc`. [See below for installation instructions.](#linux-shell-completion-scripts)
 
-On modern Debian/Ubuntu systems, install the script using
-```
-sudo cp linux_src/bash_completion/mt32-pi-ctl.bash /usr/share/bash-completion/completions/mt32-pi-ctl
-```
-On other or older distros it may need to go to `/etc/bash_completion.d/mt32-pi-ctl` instead.
 
-Alternatively you can add the line
-```
-source /path/to/mt32-pi-ctl.bash
-```
-to your `.bashrc`. After installing, you may need to relogin or reboot.
 
 #### Windows-specific options
 
@@ -147,6 +143,7 @@ OPTIONS:
 You may specify multiple options, i.e. `MT32-PI.EXE -m -t "Hello, World!"` will first send the MT-32 mode command and then the screen text.
 
 ## Building
+Note that binaries are available on the [releases page](https://github.com/gmcn42/mt32-pi-control/releases) for all platforms apart from Linux. Building `mt32-pi-ctl` on most Linux distros is very starightforward though as you'll see below. For Arch Linux users, there's also a  [package on the AUR](https://aur.archlinux.org/packages/mt32-pi-control/) now.
 
 ### DOS
 The `MAKEFILE` is written for the DOS-version of [Open Watcom C 1.9](https://sourceforge.net/projects/openwatcom/files/open-watcom-1.9/) as it can generate Real Mode executables. The Sourceforge release works perfectly in DosBox.
@@ -168,6 +165,43 @@ You need to have `gcc`, `make`, and the ALSA/libasound development headers insta
 ### Windows
 The `Makefile` is meant to be used on a Linux host with the `i686-w64-mingw32` toolchain. On Debian/Ubuntu `sudo apt install mingw-w64*` does the job. Afterwards, run `make` and `make dist` in the `win32_src` folder. If you want to compile on Windows, MSYS should work but you might need to adjust the executable names in the Makefile.
 
+## Installation
+On most platforms installation just means copying the executable file somewhere in your `PATH`, e.g. `/usr/local/bin` on Linux, `C:` on Amiga, `C:\DOS\` on DOS, and similar. Alternatively you could add the path to `mt32-pi-ctl` to your `PATH` variable if that's more to your liking.
+
+### Linux shell completion scripts
+For Linux platforms, there's the additional feature of smart command-line completion for the `bash`, `zsh`, and `fish` shells. In order for this to work you need to copy the completion scripts in `linux_src/completion_scripts/` to some special folders so your shell can find them automatically. The folders may be distro-specific but the ones below should work for Debian/Ubuntu at the very least. If in doubt, consult your distro's documentation.
+
+Note that you need `aplaymidi` installed if you want autocompletion to show you available MIDI output ports for the `-p` option. On most distros—including Debian, Ubuntu, and Arch—the package you need is called `alsa-utils`.
+
+#### bash completion script
+On modern Debian/Ubuntu systems, install the script using
+```
+sudo cp linux_src/completion_scripts/mt32-pi-ctl.bash /usr/share/bash-completion/completions/mt32-pi-ctl
+```
+On other or older distros, the bash completion script may need to go to `/etc/bash_completion.d/mt32-pi-ctl` instead.
+
+Alternatively you can add the line
+```
+source /path/to/mt32-pi-ctl.bash
+```
+to your `.bashrc`. After installing, you may need to relogin or reboot.
+
+#### fish completion script
+Install the script using
+```
+sudo cp linux_src/completion_scripts/mt32-pi-ctl.fish /usr/share/fish/vendor_completions.d/mt32-pi-ctl.fish
+```
+The fish completion script may be located in your home directory under `~/.config/fish/completions` instead, if you prefer.
+Once copied, completions should be available in fish immediately.
+
+#### zsh completion script
+Install the script using
+```
+sudo cp linux_src/completion_scripts/mt32-pi-ctl.zsh /usr/local/share/zsh/site-functions/_mt32-pi-ctl
+```
+Alternatively you may use any of the directories reported by `echo $fpath` but note that the
+script has to be renamed to `_mt32-pi-ctl` or zsh won't associate it with the program.
+After installing, you may need to relogin or reboot.
 
 ## Showcase
 <img src="https://github.com/gmcn42/mt32-pi-control/raw/main/images/mt32pictl_1.jpg" width="480">

linux_src/completion_scripts/mt32-pi-ctl.fish

@@ -0,0 +1,28 @@
+# mt32-pi-ctl fish completion script
+
+function __fish_list_midi_ports --description 'List available MIDI ports'
+    if type -q aplaymidi
+        aplaymidi -l | awk 'NR>1 {gsub(/^[[:space:]]+/, "", $1); print $1, $3}' FS='[[:space:]]{2,}' OFS='\t'
+    end
+end
+
+complete -c mt32-pi-ctl -f
+complete -c mt32-pi-ctl -s h -l help -d "Display help."
+complete -c mt32-pi-ctl -s v -l verbose -d "Be verbose about what is going on."
+complete -c mt32-pi-ctl -s r -l reboot -d "Reboot the Pi. Will block for a few secs to give it time."
+complete -c mt32-pi-ctl -s p -x -a "(__fish_list_midi_ports)" -d "The ALSA MIDI client and port address to output to."
+complete -c mt32-pi-ctl -s m -l mt32 -d "Switch mt32-pi to MT-32 mode."
+complete -c mt32-pi-ctl -s g -l fluidsynth -d "Switch mt32-pi to FluidSynth mode."
+complete -c mt32-pi-ctl -s b -l romset -x -a "(echo -e \"old\tOld MT-32 (ROM v1.xx)\nnew\tNew MT-32 (ROM v2.xx)\ncm32l\tCM-32L\n\")" -d "Switch MT-32 romset."
+complete -c mt32-pi-ctl -s s -l soundfont -x -d "Set FluidSynth SoundFont. (number)"
+complete -c mt32-pi-ctl -s S -l mt32-rstereo -x -d "Enable/disable MT-32 reversed stereo. (0, 1)"
+complete -c mt32-pi-ctl -l mt32-reset -d "Send an MT-32 reset SysEx message."
+complete -c mt32-pi-ctl -l gm-reset -d "Send a GM reset SysEx message."
+complete -c mt32-pi-ctl -l gs-reset -d "Send a GS reset SysEx message."
+complete -c mt32-pi-ctl -s t -l mt32-txt -x -d "Send an MT-32 text display SysEx."
+complete -c mt32-pi-ctl -s T -l sc55-txt -x -d "Send an SC-55 text display SysEx."
+complete -c mt32-pi-ctl -s P -l sc55-bmp -r -d "Display a 16x16 1bpp BMP on the screen. (SC-55 SysEx)"
+complete -c mt32-pi-ctl -s X -l sc55-btxt -x -d "Display a string on the screen as a Bitmap. (SC-55)"
+complete -c mt32-pi-ctl -s N -l negative -n "__fish_contains_opt -s P sc55-bmp -s X sc55-btxt" -d "Reverse color. Use with '-P/--sc55-bmp' or '-X/--sc55-btxt'."
+complete -c mt32-pi-ctl -s M -l midi -x -d "Send a list of custom MIDI bytes."
+complete -c mt32-pi-ctl -s Y -l syx -r -d "Send the contents of a SYX-file."

linux_src/completion_scripts/mt32-pi-ctl.zsh

@@ -0,0 +1,65 @@
+#compdef mt32-pi-ctl
+_mt32-pi-ctl() {
+	typeset -A opt_args
+	local context state line
+	
+	_arguments -s -S \
+		"--help[Display help.]" \
+		"-v[Be verbose about what is going on.]" \
+		"--verbose[Be verbose about what is going on.]" \
+		"-b+[Switch MT-32 romset.]:romset:->romsets" \
+		"--romset[Switch MT-32 romset.]:romset:->romsets" \
+		"-p+[The ALSA MIDI client and port address to output to.]:midi-output:->midiports" \
+		"-r[Reboot the Pi. Will block for a few secs to give it time.]" \
+		"--reboot[Reboot the Pi. Will block for a few secs to give it time.]" \
+		"-m[Switch mt32-pi to MT-32 mode.]" \
+		"--mt32[Switch mt32-pi to MT-32 mode.]" \
+		"-g[Switch mt32-pi to FluidSynth mode.]" \
+		"--fluidsynth[Switch mt32-pi to FluidSynth mode.]" \
+		"-s+[Set FluidSynth SoundFont. (number)]:SoundFont number (0-255):" \
+		"--soundfont[Set FluidSynth SoundFont. (number)]:SoundFont number (0-255):" \
+		"-S+[Enable/disable MT-32 reversed stereo. (0, 1)]:1 or 0:->rstereo" \
+		"--mt32-rstereo[Enable/disable MT-32 reversed stereo. (0, 1)]:1 or 0:->rstereo" \
+		"--mt32-reset[Send an MT-32 reset SysEx message]" \
+		"--gm-reset[Send a GM reset SysEx message]" \
+		"--gs-reset[Send a GS reset SysEx message]" \
+		"--mt32-txt[Send an MT-32 text display SysEx]:some text:" \
+		"-t+[Send an MT-32 text display SysEx]:some text:" \
+		"--sc55-txt[Send an SC-55 text display SysEx]:some text:" \
+		"-T+[Send an SC-55 text display SysEx]:some text:" \
+		"--sc55-btxt[Display a string on the screen as a Bitmap. (SC-55)]:8 characters:" \
+		"-X+[Display a string on the screen as a Bitmap. (SC-55)]:8 characters:" \
+		"--sc55-bmp[Display a 16x16 1bpp BMP on the screen. (SC-55 SysEx)]:file:_files" \
+		"-P+[Display a 16x16 1bpp BMP on the screen. (SC-55 SysEx)]:file:_files" \
+		"-N[Reverse color. Use with '-P/--sc55-bmp' or '-X/--sc55-btxt'.]" \
+		"--negative[Reverse color. Use with '-P/--sc55-bmp' or '-X/--sc55-btxt'.]" \
+		"-M[Send a list of custom MIDI bytes (in hexadecimal).]:Hexadecimal Bytes:" \
+		"--midi[Send a list of custom MIDI bytes (in hexadecimal).]:Hexadecimal Bytes:" \
+		"-Y[Send the contents of a SYX-file.]:file:_files" \
+		"--syx[Send the contents of a SYX-file.]:file:_files" \
+		&& return 0
+
+	case $state in
+		(midiports)
+			if type aplaymidi > /dev/null 2>&1; then
+				local midiports=$(aplaymidi -l | awk -F '[[:space:]][[:space:]]+' 'NR>1 { gsub(/^[ \t]+/,""); gsub(/:/,"\\:"); print $1":"$3 }')
+				midiports=(${(ps:\n:)${midiports}})
+				_describe 'Available MIDI outputs' midiports && return 0
+			else
+				return 0
+			fi
+			;;
+		(romsets)
+			local romlist=('old:Old MT-32 (ROM v1.xx)' 'new:New MT-32 (ROM v2.xx)' 'cm32l:CM-32L')
+			_describe 'romset' romlist && return 0
+			;;
+		(rstereo)
+			local desclist=('0:Disable reversed stereo' '1:Enable reversed stereo')
+			_describe 'reversed stereo' desclist && return 0
+			;;
+	esac
+
+	return 1
+}
+
+_mt32-pi-ctl

linux_src/mt32-pi-ctl.readme

@@ -1,4 +1,4 @@
-#### mt32-pi-ctl 1.0.1 Linux ReadMe ####
+#### mt32-pi-ctl 1.0.1a Linux ReadMe ####
 
 mt32-pi-ctl is a control program for the mt32-pi MIDI synthesizer.
 
@@ -37,13 +37,13 @@ OPTIONS:
 You may specify multiple options, i.e. mt32-pi-ctl -m -t "Hello, World!" will
 first send the MT-32 mode command and then the screen text.
 
-### bash completion ####
+### smart option completion ####
 
-Since version 1.0.1, the Linux version of mt32-pi-ctl also comes with an intelligent
+Since version 1.0.1a, the Linux version of mt32-pi-ctl also comes with command completion
-bash completion script that will smartly autocomplete (long) options, romsets, filenames
+scripts for bash, fish, and zsh that will smartly autocomplete (long) options, romsets, filenames
 and, if aplaymidi is in your PATH, even available MIDI ports.
 
-Examples:
+Examples for bash:
 
   $ mt32-pi-ctl -p <TAB><TAB>
     14:0  28:0
@@ -54,20 +54,46 @@ Examples:
   $ mt32-pi-ctl -p 28:0 --romset <TAB><TAB>
     cm32l  new  old
 
-For this to work mt32-pi-ctl must be in your PATH, e.g. in /usr/local/bin and the bash
+For this to work mt32-pi-ctl must be in your PATH, e.g. in /usr/local/bin and you need to copy the
-completion script must be in a special completion script directory or sourced by .bashrc.
+completion scripts in linux_src/completion_scripts/ to some special folders so your shell can find
+them automatically. The folders may be distro-specific but the ones below should work for
+Debian/Ubuntu at the very least. If in doubt, consult your distro's documentation.
+
+Note that you need aplaymidi installed if you want autocompletion to show you available MIDI output
+ports for the -p option. On most distros---including Debian, Ubuntu, and Arch---the package you need
+is called alsa-utils.
+
+## bash completion script ##
 
 On modern Debian/Ubuntu systems, install the script using
+  sudo cp linux_src/completion_scripts/mt32-pi-ctl.bash /usr/share/bash-completion/completions/mt32-pi-ctl
 
-  # cp bash_completion/mt32-pi-ctl.bash /usr/share/bash-completion/completions/mt32-pi-ctl
+On other or older distros, the bash completion script may need to go to /etc/bash_completion.d/mt32-pi-ctl
-
+instead.
-On other or older distros it may need to go to /etc/bash_completion.d/mt32-pi-ctl instead.
 
 Alternatively you can add the line
-
   source /path/to/mt32-pi-ctl.bash
+to your .bashrc.
 
-to your .bashrc. After installing, you may need to relogin or reboot
+After installing, you may need to relogin or reboot.
+
+## fish completion script ###
+
+Install the script using
+  sudo cp linux_src/completion_scripts/mt32-pi-ctl.fish /usr/share/fish/vendor_completions.d/mt32-pi-ctl.fish
+  
+The fish completion script may be located in your home directory under ~/.config/fish/completions
+instead, if you prefer.
+Once copied, completions should be available in fish immediately.
+
+## zsh completion script ##
+
+Install the script using
+  sudo cp linux_src/completion_scripts/mt32-pi-ctl.zsh /usr/local/share/zsh/site-functions/_mt32-pi-ctl
+
+Alternatively you may use any of the directories reported by echo $fpath but note that the script has to
+be renamed to _mt32-pi-ctl or zsh won't associate it with the program.
+After installing, you may need to relogin or reboot.
 
 #### BSD-License ####