X11 application launcher based on bash
bashrun [options]
bashrun is a simple application launcher for X11. It runs a bash session within a small XTerminal window, conveniently providing all the common bash features like readline, tab completion and history, while adding more features like bookmarks, regexp based handlers, dictionary lookups and google search queries.
bashrun provides two basic modes of operation, depending on whether xdotool(1) is installed on the system.
If xdotool(1) is available, the terminal hosting the bash session will be kept running in the background, hidden from display. Invoking bashrun or bashrun --show will show and focus the window; after issuing a command, the terminal window will be hidden from display again. This method reduces startup time and saves system resources.
If xdotool(1) is not installed, a new instance is created on each invocation, immediately terminating after running the first command.
-v, --version
print version information
-h, --help
print usage information
-d, --debug
start in debug mode
If xdotool(1) is available, the following options control a running bashrun instance from subsequent invocations. Note that if no previous bashrun instance is found, options --show, --toggle, --restart, --su and --debug will start a new bashrun session.
--show
map the window and focus it
--hide
unmap the window
--toggle
toggle window visibility
--exit
terminate an existing bashrun process
--restart
restart bashrun (required to apply configuration file changes)
--su command
run command with root privileges. Brings up the bashrun terminal for password entry.
Type text into bashrun and invoke key sequences remotely. See the key command in xdotool(1) for the syntax of <keyseq>.
--wid
print the terminal's window id
--wait
wait until terminal window is unmapped
--debug
toggle debug mode
Running simple commands is straightforward. The shell will perform the usual expansions and the resulting command is handled and launched according to the user requested action and preferences.
Multiple commands separated by ; are successively handled in the same manner.
If commands are separated by a pipe symbol (|) or by the logical operators || or && then bashrun's behavior will substantially differ from the normal shell behavior. To the bashrun shell, every simple command in a compound statement will appear as though it immediately returns success. This means that separating commands with && or | is effectively equivalent to using ;. Separating commands with || will prevent the execution of commands on the right hand side of the expression.
To circumvent this behavior, the characters ;, & and | can be escaped with a backslash character (\). Please note that in this case terminal rules are only applied based on the command name of the first command.
To illustrate, a command like
$ cat textfile | wc -l <term-page>
will fail to work as intended and instead page the output of both commands in separate terminals, with no pipe established between the commands. You will need to use
$ cat textfile \| wc -l <term-page>
to page the number of lines in textfile in a single terminal window as intended.
Editing multiple lines does not work in bashrun. If you happen to forget a closing quote on your commandline, bashrun will ask you to press C-c. Your last history line may be bogus after this.
To run commands in the context of the bashrun shell session instead of having them handled by bashrun, use the <pass> action (default: M-w).
Keybindings can be configured in the keyboard configuration file $XDG_CONFIG_HOME/bashrun/keys. This file contains keymap directives and keybinding definitions.
The keymap directive chooses the readline keymap that subsequent keybinding definitions will be bound to. The syntax is
KEYMAP <keymap>
where <keymap> is either emacs, vi-insert or vi-command.
The syntax for keybinding definitions is
<action> <keyseq> [<keyname>]
where <action> is the name of the bashrun action (see ACTIONS below), keyseq is a valid readline(1) key sequence, and <keyname> is an optional human-readable name for the key sequence (used to display the keybindings to the user).
Please note that all key sequences beginning with C-x[0-9] as well as the literal characters \\201 up to \\209 are reserved for internal use and can not be used.
Lines beginning with # are comments and will be ignored.
This section lists all actions that can be bound to key sequences. Use the <bashrun-bindings> action (default: F1) in the to show the current keybindings.
Quit bashrun. Terminates the bashrun shell session.
Hide the window (using xdotool) or quit.
Execute command in the context of the bashrun shell session, bypasses command handling.
Execute the command.
Execute the command in a terminal.
Execute the command in a terminal and hold.
Execute the command in a terminal and page output using PAGER.
Execute the command with root privileges. You will be prompted for the password first.
Execute the command with root priviledges in a terminal.
Execute the command with root privileges in a terminal and hold.
Execute the command with root privileges in a terminal and page output using PAGER.
Show the manual page for the command in a terminal.
Show the info page for the command in a terminal.
Page help for bash builtin commands in terminal. Tries to show the manual page if the command is not a bash builtin.
Copy command output to clipboard (using xclip).
Copy command output and paste it to window under the mouse cursor (using xclip and xdotool).
Pipe clipboard contents into command and copy output to cliboard (using xclip).
Pipe clipboard contents into command and copy output to cliboard, then paste to window under the mouse cursor (using xclip and xdotool).
Browse words in BROWSER, see CONFIGURATION FILE
Google words in BROWSER, see CONFIGURATION FILE
Look up words in dictionary, requires dict(1) or similar. Use the config option DICT_CLIENT to use a different client, see CONFIGURATION FILE
Show the current keybindings in a terminal.
Show this manual in a terminal.
Show current HANDLERS in a terminal.
Toggle debugging messages on/off. Sets KEEP_OPEN and resizes the terminal to 80x24 if supported.
Toggle between "small" and "large" size (xterm, *rxvt only). See CONFIGURATION FILE.
Resize the terminal. (xterm, *rxvt only)
The user configuration file $XDG_CONFIG_HOME/bashrun/rc will be sourced as the rcfile for the bash session used by bashrun. Apart from the environment variables described here you can add anything that you would usually add to your ~/.bashrc file. For example, you might want to add functions or aliases, bind additional function keys or simply source your existing ~/.bashrc file.
Please make sure that you don't interfere with the tty/bash settings and reserved keybindings used by bashrun. See KEYBOARD CONFIGURATION FILE and ENVIRONMENT or take a look at $PREFIX/share/bashrun/bashrc.
XTERM=[xterm|rxvt|urxvt|urxvtc|mrxvt|aterm|mlterm] (default: xterm)
The terminal to be used for bashrun.
XTERM_OPTIONS=[...] (default: empty)
Additional commandline options to be passed to the terminal.
KEEP_OPEN=[yes|no] (default: no)
If set to "yes", the terminal won't be hidden after every command. Subsequent invocations of bashrun or bashrun --show will focus the terminal window, <abort> or bashrun --hide will unfocus the window and give focus back to the previously focused application.
SMALL_COLUMNS=n, SMALL_LINES=n (default: 40x1)
Size of the terminal in the default "small" mode.
LARGE_COLUMNS=n, LARGE_LINES=n (default: 40x8)
Size of the terminal in "large" mode, toggled via <toggle-size> (xterm and *rxvt only).
FGCOLOR=color, BGCOLOR=color (default: grey on black)
Foreground and background color of the terminal. Consult your terminal's documentation for possible values.
PS1=[...] (default: '>')
Prompt string, see bash(1)
HISTCONTROL (default: ignoredups:erasedups)
History settings, see bash(1)
COMPLETION_TYPE=[complete|menu-complete|quiet-complete] (default: menu-complete)
For complete and menu-complete, see bash(1). The quiet-complete mode will use complete and additionally set the following readline variables:
page-completions off
print-completions-horizontally on
completion-query-items -1
The quiet-complete mode is useful if you want completion to behave like complete but without being interrupted by readline prompts. Although completions are actually printed you will effectively not see them in a one-line-terminal.
ALTERNATIVE_COMPLETION_TYPE=[complete|menu-complete|quiet-complete] (default: complete)
The completion type to switch to if LINES >= COMPLETION_THRESHOLD, see below.
COMPLETION_THRESHOLD=[num_lines] (default: LARGE_LINES)
If the number of LINES in the terminal is equal or greater than this value, switch to ALTERNATIVE_COMPLETION_TYPE. If the value is less than 1, this feature is disabled.
(Note: the default setup for these options results in using menu-complete in "small" mode and complete in "large" mode.)
USE_EXTENDED_BASH_COMPLETION=[yes|no] (default: no)
Whether to use extended bash completion.
EXTENDED_BASH_COMPLETION_PATH=[path]
(default: /etc/profile.d/bash_completion.sh) Path to a script enabling extended bash completion. Consult your distribution's documentation.
POST_MAP_COMMAND=[command] (default: not set)
Command to run directly after making the window visible via xdotool. E.g. you could set the transparency of the window to 75% using transset -a 0.75 when running xcompmgr.
DICT_CLIENT=[command] (default: dict --pager $PAGER)
Which dict client to use for the <dict-lookup> action. Add your client to the TERMINAL_RULES if neccessary.
DIRHANDLER=[command] (default: not set)
A command to be run when a path to a directory is entered and the directory is readable. The path will be passed as the first argument to the specified command.
BROWSER=[command] (default: firefox)
Browser to use for google search and default handlers (see below).
GOOGLE_FALLBACK=[yes|no] (default: no)
If set to yes bashrun will automatically google the commandline if it isn't executable or if it's not handled by HANDLERS or DIRHANDLER
TERMINAL_RULES=('RUN:[progs]' 'PAGE:[progs]' 'HOLD:[progs]')
An array containing rule strings that define which programs should always be launched in a terminal window. Insert a space separated list of program names after the : into the string for the desired rule. Programs in the RUN rule are always launched in a terminal. Programs in the PAGE rule will have their output paged in PAGER. For programs in the HOLD rule the terminal is kept open after the program terminates.
Example:
TERMINAL_RULES=(
"RUN:watch top htop less man info ncftp links"
"HOLD:ps su"
"PAGE:echo ls which uname lsusb lshal lsmod fortune"
)
HANDLERS=([regexp handler]...) (defaults: see below)
An array containing bash regular expressions and associated handler strings. If the commandline entered into bashrun is not executable (i.e. it's not a function, alias or a binary on PATH) then an attempt is made to successively match the commandline against the patterns contained in HANDLERS. If a pattern matches, either the handler string following the pattern will be used as the command to execute, with the commandline itself passed as the argument, or, if the regexp contains subpatterns within parenthesis, an attempt is made to substitute the occurrence of $[1-9] in the handler string with the contents of the corresponding subpattern match. The modified handler string is then used as the commandline without adding further arguments.
If there are not enough subpattern matches to substitute every occurrence of $[0-9] in the handler string then the handler will not be executed and an error message will be issued to the user.
The handler string may additionally be prefixed with a file test expression defining a series of file tests to be performed on the contents of the commandline prior to applying the handler. If any of these tests fail, the handler will not be applied.
The test expression is a series of characters corresponding to the unary file test operators defined in section CONDITIONAL EXPRESSIONS of the bash(1) manual, terminated by :. File tests can be negated by prefixing them with a single !. E.g. a handler prefixed with f!x: will only be applied if the commandline is a path to a regular, non-executable file.
For example, to define file associations for jpeg files you can use a pattern and handler like
'\.jpe?g$' 'f!x:gimp'
This will open lines ending in .jpg or .jpeg using gimp(1). The file test ensures that you can still type a line like
$ convert foo.tif foo.jpg
which will not be handled although it also ends in .jpg. This is because the test expression is applied to the complete line, so the f!x test will fail.
To open lines beginning with http or https in your BROWSER, add a line like this to the HANDLERS array:
'^https?' "$BROWSER"
To implement web shortcuts similar to KDE's konqueror browser, use a pattern containing a subpattern, like this:
'^gg:(.+)'
and use a line like this as the handler string:
"$BROWSER 'http://www.google.com/search?q=\$1'"
Bashrun will replace the $1 part of the handler string with anything the user has entered after gg:.
See the default user configuration file for more examples. if your handlers don't work as expected, turn on debug mode to see what is going on.
The following handlers are setup by default if the default configuration file is being used or HANDLERS is not set in the user configuration file:
^www, ^https?
|
Open lines beginning with www, http or https in BROWSER |
|---|---|
^gg:(.+)
|
|
^ggl:(.+)
|
Google using "I'm feeling lucky" |
^fm:(.+)
|
Search for project on freshmeat.net |
^sf:(.+)
|
Visit project page on sourceforge.net |
^sfw:(.+)
|
Visit project website on sourceforge.net |
\.jpe?g$
|
Open JPEG files in gimp, using f!x as test expression |
^ftp:(.+)
|
Start ncftp $1 in xterm |
^\?(.+)
|
Page $1 --help in xterm |
^\?\?(.+)
|
Show man $1 in xterm |
BOOKMARKS=([bookmark]...) (default: see example)
An array of strings that will be added to the possible command completions. Make sure there is a handler defined in HANDLERS for each of the strings used as bookmarks. Example:
BOOKMARKS=(
www.google.com
www.archlinux.org
www.slashdot.org
www.linux.com
http://bashrun.sourceforge.net
)
LOGFILE=[path] (default: /dev/null)
Command output (stdout and stderr) is appended to LOGFILE. If it doesn't exist, bashrun will attempt to create it. If it is not writeable, output is redirected to /dev/null instead.
Logging is disabled for commands run with root privileges.
$XDG_CONFIG_HOME/bashrun/rc
The user configuration file. If it does not exist, it will be created and initialized with the default configuration.
$XDG_CONFIG_HOME/bashrun/keys
The keyboard configuration file. If it does not exist, it will be created and initialized with the default keybindings.
If xdotool(1) is used, bashrun needs to be restarted to make changes to these files take effect.
If XDG_CONFIG_HOME is not set or empty, ~/.config will be used instead.
$XDG_DATA_HOME/bashrun/history
The history file used by bashrun. If XDG_DATA_HOME is not set or empty, ~/.local/share will be used instead.
$XDG_CACHE_HOME/bashrun/
Directory for temporary files created by bashrun. If XDG_CACHE_HOME is not set or empty, ~/.cache will be used instead.
X11
The Window manager properties WM_CLASS and WM_NAME are set to "bashrun". These properties can be used with your window manager's facilities to further configure the appearance of bashrun. Note that if you are using xdotool(1) it is recommended to make the bashrun window "sticky" to make sure it will always appear on the current desktop.
BASH
The extdebug shell option is enabled. A trap on DEBUG is set each time a commandline is issued. The trap is disabled again after commandline processing to prevent it from interfering with interactive commandline editing.
Sending ^D (eof) on an empty line does not terminate the shell if xdotool(1) is being used. See stty(1)
XON/XOFF flow control (Suspend/Resume terminal via C-s and C-q) is disabled. C-s will search forward in the history buffer (readline default) while C-q is bound to the <quit> action when using the default keybindings. See stty(1)
Some terminals require quoting of the commandline to be run. This means that running commandlines with lots quoting may fail for these terminals, although two levels of quoting should generally work. You can use the debug mode to find out exactly why and how a heavily quoted command fails.
Only xterm(1) and *rxvt(1) support resizing using keybindings. xterm has occasionally been found to freeze during resizing, requiring at least a SIGTERM to close it.
For XTerm, the allowWindowOps resource needs to be set to True to allow window resizing. This is enabled in the default configuration for xterm as of bashrun version 0.14. Note that setting allowSendEvents to True will forcefully disable allowWindowOps in XTerm.
In order for meta keybindings (prefixed with \e or \M-) to work with the Alt or Meta key, the terminal needs to be configured to translate your meta key to an escape. For XTerm, this can be enabled by setting the metaSendsEscape resource to True. This is enabled in the default configuration for xterm as of bashrun version 0.14. For URxvt, the meta8 resource needs to be set to False (which is the default setting for URxvt).
Daniel J. Griffiths (aka Ghost1227) <ghost1227 at archlinux dot us>
|
Sourceforge hosting, website design, ArchLinux packaging |
|---|---|
Shapeshifter
|
Suggestions, code, bug reports |
Bernard Walle
|
Bug reports, OpenSuse packaging |
Dieter Plaetinck
|
Bug reports |
Wouter Koersen
|
Suggestions, code |
Mathias Dahl
|
Suggestions, bug reports |
Reuben Thomas
|
Suggestions, bug reports |
bashrun - http://bashrun.sourceforge.net
xdotool - http://www.semicomplete.com/projects/xdotool
dict - http://www.dict.org/