NAME
bosh - Browsable Output SHell
SYNOPSIS
bosh [OPTIONS] [CONFIGURATION] [CONFIGURATION OPTIONS]
DESCRIPTION
bosh takes the output of a program or script and provides a curses
interface to browse that output. A particular line of that output can
be selected and actions can be defined and executed and make use of the
that selected line.
USAGE
CONFIGURATION is the name of a bosh configuration file (see below), in
which case that is loaded.
If CONFIGURATION is absent, and bosh is invoked on the end of a pipe,
it will read from stdin.
Bosh now supports passing arguments to the CONFIGURATION. The arguments
will be available in the standard way ($1...$9,$*,$@,etc).
Bosh can be invoked as above, or as "intepreter", meaning it can
invoked from a shebang (#!) line at the top of a script. This script
would just be a bosh configuration file. See bops as an example, which
should have come with bosh.
OPTIONS
-h / --help
show help and exit
-v / --version
show version and exit
--autorefresh=N
Automatically re-run command every N seconds.
--cursorsize=N
Set the cursor to N lines high.
--cursormovement=N
Set how much the cursor moves one an up/down keypress.
--header=[N]
Prevent the cursor from entering the first N rows of the output.
--multilineseperator=STRING
When an action is invoked and the cursor is multi-line, the
lines selected will be concatenated together. With this setting
a seperating string can be specified to be inserted between the
lines.
--preaction=COMMANDS
A command or commands that will be run on the invokation of all
actions, before the action is run. This allows code that is a
common for the actions to be only defined once. Preactions are
simply prefixed onto the action when the action is invoked. This
means you will need to include a seperating character (eg ;) at
the end of preaction.
--refresh=[0,1]
A value of 1 means that bosh will re-run the command after an
action is perfromed.
--uservars=N
Set the number of user variables ( of the form $BOSHVARx )
available. See the USER VARIABLES section below.
CONFIGURATION FILES
Bosh configs are fairly simple. Firstly you need a line which tells
bosh the actual program to execute to show it it’s buffer -
command=ps x
It could also be a chain of commands (bash) -
command=for i in *; do echo $i; done
Or it can spread it over multiple lines for readablity with a \ (must
be at the end of line!) -
command=for i in * \
do \
echo $i \
done
Or now even better, bosh supports blocks delimited by {{ and }} -
command{{
for i in *
do
echo $i
done
}}
These can be used with all options and actions.
Command line arguments given to bosh after the COMMAND parameter are
available and can be used as follows -
command=ps $*
This would allow the user to specify the format of ps when invoking
bosh.
Commands can also set BOSHERR. When execution of the command finishes,
bosh will exit and display the value of BOSHERR if it has been set.
command=if [ -z "$1" ] \
then \
BOSHERR="usage: $BOSHCONF [SECTION] NAME" \
return 1 \
fi \
man $*
This will mean bosh exits immediately if no arguments are passed on the
command line. Note the use of return rather than exit.
After the command option, you can specify any of the options specified
above in the OPTIONS section, but without the -- prefix -
header=4
refresh=1
ACTIONS
Basic actions are defined as -
KEY=command
eg:
k=kill $(echo $BOSH | cut -f1 -d’ ’)
9=kill -9 $(echo $BOSH | cut -f1 -d’ ’)
Or, using the preaction setting (see above) -
preaction=PID=$(echo $BOSH | cut -f1 -d’ ’);
k=kill $PID
9=kill -9 $PID
The keys available are a-z,0-9 and enter. Bosh keys are not case
sensitive, so A= is the same as a=.
$BOSH is an environment variable containing the currently selected
line(s) in bosh. It is set when the action key is invoked. This is how
information is passed to the actions. In the example above, the PID is
extracted from the currently selected line of the ps output using cut,
which can then be passed to the kill command.
ACTIONS WITH OUTPUT
For basic actions such as kill, which has no output to stdout, the
above definition is sufficient. However, bosh can now intercept the
output of actions and place that in the bosh window. These are defined
as follows -
KEY=[.]command
Or,
eg:
l=[.]/usr/sbin/lsof -p $PID
Assuming the preaction is used above, this action will use lsof to show
in bosh a list of files that process $PID has open. In this situation,
the output of the original command is lost, and replaced with the
output of the action.
Alternatively an action can be defined -
KEY=[>]command
In this situation, bosh is like a web browser, in that this output
(lsof) will not override the current buffer, but create a new buffer -
You can get then move back and forward through these buffers with the
left and right arrow keys. At this stage, actions are only available in
the original buffer.
The other possibility is that an action may be required that has output
that isn’t to be shown in the bosh window, such as other curses-based
applications. So the following syntax will make bosh end curses mode
when this action is invoked.
KEY=[!]command
eg: If the bosh window contained a list of files, an action like this
could be used to load that file in pico.
e=[!]pico $BOSH
ACTION PARAMETERS
Actions can now have a prompt for user input before performing the
action. The value is available to the action using the $BOSHPARAM
variable.
eg: Using the ps example above, with PID preaction -
s=[!:signal] kill -s $BOSHPARAM $PID
When this action is called, bosh will ask for user input with the
prompt signal: . Once this has been entered, the action will run.
BOSH* VARIABLES:
In addtion to $BOSH , $BOSHPARAM and $BOSHERR (all explained above),
the following variables available to actions -
$BOSHPID
Process ID of bosh itself
$BOSHPPID
Parent process ID of bosh (eg: the shell you ran bosh from)
USER VARIABLES
User variables are variables to be set and used by commands and
actions. They are of the form $BOSHVARx. When the command or action is
run and sets a user variable, bosh will store the contents when that
command or action has finised. This allows the values to be used by
subsequent actions. To make use of these, you must first set the
uservars to the number you need (eg: uservars=1 will give you BOSHVAR1,
uservars=10 will give you BOSHVAR1 thru BOSHVAR10).
SHELLS
Currently bosh only supports bash as the shell that it spawns for
executing the commands and actions. Support for other shells and
languages will hopefully be included in the future.
EXAMPLE CONFIGURATION:
Included with bosh should be a simple configuration named bops. It uses
ps as the main command, and allows you to kill the selected process or
view its open files (using lsof). This is where the above examples are
taken from. The original inspiration for bosh was being able to kill
processes easily in this manner.
To run bops, type -
$ ./bops
This invokes bosh through the shebang at the top (assuming the path is
set correctly).
Or to run it the traditional way -
$ ./bosh ./bops
KEYS
UP/DOWN
cursor up/down
LEFT/RIGHT
buffer forward/back
^L refresh screen
^O run new command
^P pipe buffer through a command, with the output of that pipe will
become the buffer
^R refresh program output (re-run the command)
^V show the current configuration
^W search
^N repeat search
^X exit
F3 same as ^W
F4 same as ^N
F5 same as ^R
F6 reload configuration
F12 same as ^L
| same as ^P
STATUS BAR
The status bar contains some further information about the current
configuration. It shows with exit=num the last exit value of a command
run in bosh. Furthermore a R indicates that bosh is running with
refresh option activated. In the status bar there will be a countdown
shown if the autorefresh option is set.
AUTHOR
Alex Sisson (alexsisson@gmail.com)
HOMEPAGE
Check for updates at http://bosh.sourceforge.net