BASHRUN(1) | User Manuals | BASHRUN(1) |
NAME
bashrun - X11 application launcher based on bash
SYNOPSIS
bashrun [options]
DESCRIPTION
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.
OPTIONS
- -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.
- --remote type <text> key <keyseq> ...
- 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 COMMANDS
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).
KEYBOARD CONFIGURATION FILE
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.
ACTIONS
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
- Quit bashrun. Terminates the bashrun shell session.
- abort
- Hide the window (using xdotool) or quit.
- pass
- Execute command in the context of the bashrun shell session, bypasses command handling.
- run
- Execute the command.
- term-run
- Execute the command in a terminal.
- term-hold
- Execute the command in a terminal and hold.
- term-page
- Execute the command in a terminal and page output using PAGER.
- su-run
- Execute the command with root privileges. You will be prompted for the password first.
- su-term-run
- Execute the command with root priviledges in a terminal.
- su-term-hold
- Execute the command with root privileges in a terminal and hold.
- su-term-page
- Execute the command with root privileges in a terminal and page output using PAGER.
- show-manual
- Show the manual page for the command in a terminal.
- show-info
- Show the info page for the command in a terminal.
- show-help
- Page help for bash builtin commands in terminal. Tries to show the manual page if the command is not a bash builtin.
- copy
- Copy command output to clipboard (using xclip).
- copy-paste
- Copy command output and paste it to window under the mouse cursor (using xclip and xdotool).
- filter
- Pipe clipboard contents into command and copy output to cliboard (using xclip).
- filter-paste
- Pipe clipboard contents into command and copy output to cliboard, then paste to window under the mouse cursor (using xclip and xdotool).
- browse
- Browse words in BROWSER, see CONFIGURATION FILE
- google-search
- Google words in BROWSER, see CONFIGURATION FILE
- dict-lookup
- Look up words in dictionary, requires dict(1) or similar. Use the config option DICT_CLIENT to use a different client, see CONFIGURATION FILE
- bashrun-bindings
- Show the current keybindings in a terminal.
- bashrun-manual
- Show this manual in a terminal.
- bashrun-handlers
- Show current HANDLERS in a terminal.
- bashrun-debug
- Toggle debugging messages on/off. Sets KEEP_OPEN and resizes the terminal to 80x24 if supported.
- toggle-size
- Toggle between "small" and "large" size (xterm, *rxvt only). See CONFIGURATION FILE.
- resize-[up|down|left|right]
- Resize the terminal. (xterm, *rxvt only)
CONFIGURATION FILE
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)
XTERM_OPTIONS=[...] (default: empty)
KEEP_OPEN=[yes|no] (default: no)
SMALL_COLUMNS=n, SMALL_LINES=n (default: 40x1)
LARGE_COLUMNS=n, LARGE_LINES=n (default: 40x8)
FGCOLOR=color, BGCOLOR=color (default: grey on black)
PS1=[...] (default: '>')
HISTCONTROL (default: ignoredups:erasedups)
COMPLETION_TYPE=[complete|menu-complete|quiet-complete] (default: menu-complete)
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)
COMPLETION_THRESHOLD=[num_lines] (default: LARGE_LINES)
(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)
EXTENDED_BASH_COMPLETION_PATH=[path]
POST_MAP_COMMAND=[command] (default: not set)
DICT_CLIENT=[command] (default: dict --pager $PAGER)
DIRHANDLER=[command] (default: not set)
BROWSER=[command] (default: firefox)
GOOGLE_FALLBACK=[yes|no] (default: no)
TERMINAL_RULES=('RUN:[progs]' 'PAGE:[progs]' 'HOLD:[progs]')
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)
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)
BOOKMARKS=(
www.google.com
www.archlinux.org
www.slashdot.org
www.linux.com
http://bashrun.sourceforge.net
)
Logging is disabled for commands run with root privileges.
FILES
$XDG_CONFIG_HOME/bashrun/rc
$XDG_CONFIG_HOME/bashrun/keys
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
$XDG_CACHE_HOME/bashrun/
ENVIRONMENT
- 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
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)
KNOWN ISSUES
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).
BUGS
Please report any bugs you may find using the email address below. Comments and suggestions are also welcome.
AUTHOR
Henning Bekel <h.bekel at googlemail dot com> (english and german)
CONTRIBUTORS
- 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
REFERENCES
bashrun - http://bashrun.sourceforge.net
xdotool - http://www.semicomplete.com/projects/xdotool
dict - http://www.dict.org/
SEE ALSO
Xorg(1), xterm(1), xdotool(1), dict(1), stty(1), bash(1), readline(3)
June 2009 | Linux |