bb/API.md

BB's API

In bb, all interaction (more or less) occurs through binding keypresses (and mouse events) to shell scripts. These shell scripts can perform external actions (like moving files around) or internal actions (like changing the directory bb is displaying). When a shell script runs, bb creates a temporary file, and scripts may write commands to this file to modify bb's internal state.

Helper Functions

• bb: used for modifying bb's internal state (see BB Commands).
• ask: get user input in a standardized and customizable way. The first argument is a variable where the value is stored. The second argument is a prompt. A third optional argument can provide a default value (may be ignored).
• ask1: get a single character of user input. The first argument is a variable where the input will be stored and the second argument is a prompt.
• pause: Display a "press any key to continue" message and wait for a keypress.
• confirm: Display a "Is this okay? [y/N]" prompt and exit with failure if the user does not press 'y'.
• spin: Display a spinning icon while a slow command executes in the background. (e.g. spin sleep 5).

Environment Variables

For startup commands and key bindings, the following values are provided as environment variables:

• $@ (the list of arguments): the full paths of the selected files
• $BBCURSOR: the full path of the file under the cursor
• $BBDEPTH: the number of bb instances deep (in case you want to run a shell and have that shell print something special in the prompt)
• $BBCMD: a file to which bb commands can be written (used internally)
• $BBGLOB: the glob pattern bb is using to determine which files to show

BB Internal State Commands

In order to modify bb's internal state, you can call bbcmd <cmd>, where "cmd" is one of the following commands (or a unique prefix of one):

• bind:<keys>:<script> Bind the given key presses to run the given script
• cd:<path> Navigate to
• columns:<columns> Change which columns are visible, and in what order
• deselect[:<filename>] Deselect (default: all selected files)
• fg[:num] Send a background process to the foreground (default: most recent process)
• glob:<glob pattern> The glob pattern for which files to show (default: *)
• goto:<filename> Move the cursor to (changing directory if needed)
• help Show the help menu
• interleave[:01] Whether or not directories should be interleaved with files in the display (default: toggle)
• move:<num*> Move the cursor a numeric amount
• quit Quit bb
• refresh Refresh the file listing
• scroll:<num*> Scroll the view a numeric amount
• select[:<filename>] Select (default: all visible files)
• sort:([+-]method)+ Set sorting method (+: normal, -: reverse, default: toggle), additional methods act as tiebreaker
• spread:<num*> Spread the selection state at the cursor
• toggle[:<filename>] Toggle the selection status of (default: all visible files)

For any of these commands (e.g. select), an empty parameter followed by additional arguments (e.g. bbcmd select: <file1> <file2> ...) is equivalent to repeating the command with each argument (e.g. bbcmd select:<file1> select:<file2> ...).

Note: for numeric-based commands (like scroll), the number can be either an absolute value or a relative value (starting with + or -), and/or a percent (ending with %). Scrolling and moving, % means percent of screen height, and %n means percent of number of files (e.g. +50% means half a screen height down, and 100%n means the last file)

Globbing

bb uses glob patterns to determine which files are visible. By default, the pattern is *, which means all files except those starting with a . (dot). bb's globs are POSIX-compliant and do not support bash-style extensions like ** for recursive matches. bb supports multiple, space-separated globs, so for example, you can display all files including dotfiles with the glob: .* * (by default, pressing the . key will toggle this behavior). The current bb glob is available in $BBGLOB, which can be used in scripts if left unquoted.

Final Notes

Internally, bbcmd writes the commands (NUL terminated) to a file whose path is in$BBCMD and bb reads from that file when it resumes. These commands can also be passed to bb at startup as command line arugments starting with +, and will run immediately. E.g. bbcmd +'col:n' +'sort:+r' . will launch bb only showing the name column, randomly sorted.

bb also optimizes any scripts that only contain just a bbcmd command and no shell variables, other commands, etc. (e.g. bbcmd move:+1) These bbcmd-command-only scripts directly modify bb's internal state without spawning a shell, so they're much faster and avoid flickering the screen.