Skip to content

Commit

Permalink
Merge pull request #6 from dwhinham/fish-completion
Browse files Browse the repository at this point in the history
Add fish and zsh completion scripts and installation instructions in Readmes
  • Loading branch information
gmcn42 authored Aug 14, 2021
2 parents 246199d + f938bd4 commit 7cb4c42
Show file tree
Hide file tree
Showing 5 changed files with 179 additions and 26 deletions.
62 changes: 48 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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
by `.bashrc`.
bash/fish completion scripts must be in a special completion script directory or for bash, sourced
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

Expand Down Expand Up @@ -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.
Expand All @@ -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">
Expand Down
File renamed without changes.
28 changes: 28 additions & 0 deletions linux_src/completion_scripts/mt32-pi-ctl.fish
Original file line number Diff line number Diff line change
@@ -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."
65 changes: 65 additions & 0 deletions linux_src/completion_scripts/mt32-pi-ctl.zsh
Original file line number Diff line number Diff line change
@@ -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
50 changes: 38 additions & 12 deletions linux_src/mt32-pi-ctl.readme
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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
bash completion script that will smartly autocomplete (long) options, romsets, filenames
Since version 1.0.1a, the Linux version of mt32-pi-ctl also comes with command completion
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
Expand All @@ -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
completion script must be in a special completion script directory or sourced by .bashrc.
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 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.

On modern Debian/Ubuntu systems, install the script using
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.

# cp bash_completion/mt32-pi-ctl.bash /usr/share/bash-completion/completions/mt32-pi-ctl
## bash completion script ##

On other or older distros it may need to go to /etc/bash_completion.d/mt32-pi-ctl instead.
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

Alternatively you can add the line
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

to your .bashrc. After installing, you may need to relogin or reboot
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 ####

Expand Down

0 comments on commit 7cb4c42

Please sign in to comment.