(101 lines)

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 is bundled with some helper scripts for performing common tasks. These scripts are installed to /etc/bb/, which is added to bb's $PATH environment variable at runtime. ~/.config/bb/ is also added to the $PATH with higher priority, so you can override any of these scripts by putting your own version there.

bbstartup: The script run when bb first launches. It calls bbkeys by default and sets up some configuration settings like which columns to display.
bbkeys: The script called by bb to create all of bb's key bindings. It's currently very hacky, but it amounts to a bunch of calls to bbcmd bind:<key>:<script>
bbshutdown: The script run when bb exits. The default implementation saves the current configuration settings to ~/.local/share/bb/settings.sh, which is run by bbstartup to restore the settings at launch.
bbask [-1] [prompt [initial]]: Get user input in a standardized and customizable way and output it to STDOUT.
bbcmd <cmd>*: Modifybb's internal state (see BB Commands).
bbconfirm [prompt]: Display a "Is this okay? [y/N]" prompt and exit with failure if the user does not press 'y'.
bbpause: Display a "press any key to continue" message and wait for a keypress.
bbpick [prompt]: Select one of NULL-delimited multiple inputs and print it.
bbunscroll: Print text to the screen above the cursor instead of below it.

Environment Variables

When bb runs scripts, following values are provided as environment variables:

$@ (the list of arguments): the full paths of the selected files
$BB: 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 (NULL 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.

   1 # BB's API
   2 
   3 In `bb`, all interaction (more or less) occurs through binding keypresses
   4 (and mouse events) to shell scripts. These shell scripts can perform external
   5 actions (like moving files around) or internal actions (like changing the
   6 directory `bb` is displaying). When a shell script runs, `bb` creates a
   7 temporary file, and scripts may write commands to this file to modify `bb`'s
   8 internal state.
   9 
  10 ## Helper Functions
  11 
  12 `bb` is bundled with some helper scripts for performing common tasks. These
  13 scripts are installed to `/etc/bb/`, which is added to `bb`'s `$PATH`
  14 environment variable at runtime. `~/.config/bb/` is also added to the `$PATH`
  15 with higher priority, so you can override any of these scripts by putting your
  16 own version there.
  17 
  18 - `bbstartup`: The script run when `bb` first launches. It calls `bbkeys` by
  19   default and sets up some configuration settings like which columns to display.
  20 - `bbkeys`: The script called by `bb` to create all of `bb`'s key bindings.
  21   It's currently very hacky, but it amounts to a bunch of calls to `bbcmd
  22   bind:<key>:<script>`
  23 - `bbshutdown`: The script run when `bb` exits. The default implementation saves
  24   the current configuration settings to `~/.local/share/bb/settings.sh`, which
  25   is run by `bbstartup` to restore the settings at launch.
  26 - `bbask [-1] [prompt [initial]]`: Get user input in a standardized and
  27   customizable way and output it to `STDOUT`.
  28 - `bbcmd <cmd>*`: Modify`bb`'s internal state (see BB Commands).
  29 - `bbconfirm [prompt]`: Display a "Is this okay? [y/N]" prompt and exit with
  30   failure if the user does not press 'y'.
  31 - `bbpause`: Display a "press any key to continue" message and wait for a keypress.
  32 - `bbpick [prompt]`: Select one of `NULL`-delimited multiple inputs and print it.
  33 - `bbunscroll`: Print text to the screen *above* the cursor instead of below it.
  34 
  35 ## Environment Variables
  36 
  37 When `bb` runs scripts, following values are provided as environment variables:
  38 
  39 - `$@` (the list of arguments): the full paths of the selected files
  40 - `$BB`: the full path of the file under the cursor
  41 - `$BBDEPTH`: the number of `bb` instances deep (in case you want to run a
  42   shell and have that shell print something special in the prompt)
  43 - `$BBCMD`: a file to which `bb` commands can be written (used internally)
  44 - `$BBGLOB`: the glob pattern `bb` is using to determine which files to show
  45 
  46 ## BB Internal State Commands
  47 
  48 In order to modify bb's internal state, you can call `bbcmd <cmd>`, where "cmd"
  49 is one of the following commands (or a unique prefix of one):
  50 
  51 - `bind:<keys>:<script>`     Bind the given key presses to run the given script
  52 - `cd:<path>`                Navigate to <path>
  53 - `columns:<columns>`        Change which columns are visible, and in what order
  54 - `deselect[:<filename>]`    Deselect <filename> (default: all selected files)
  55 - `fg[:num]`                 Send a background process to the foreground (default: most recent process)
  56 - `glob:<glob pattern>`      The glob pattern for which files to show (default: `*`)
  57 - `goto:<filename>`          Move the cursor to <filename> (changing directory if needed)
  58 - `help`                     Show the help menu
  59 - `interleave[:01]`          Whether or not directories should be interleaved with files in the display (default: toggle)
  60 - `move:<num*>`              Move the cursor a numeric amount
  61 - `quit`                     Quit `bb`
  62 - `refresh`                  Refresh the file listing
  63 - `scroll:<num*>`            Scroll the view a numeric amount
  64 - `select[:<filename>]`      Select <filename> (default: all visible files)
  65 - `sort:([+-]method)+`       Set sorting method (+: normal, -: reverse, default: toggle), additional methods act as tiebreaker
  66 - `spread:<num*>`            Spread the selection state at the cursor
  67 - `toggle[:<filename>]`      Toggle the selection status of <filename> (default: all visible files)
  68 
  69 For any of these commands (e.g. `select`), an empty parameter followed by
  70 additional arguments (e.g. `bbcmd select: <file1> <file2> ...`) is equivalent to
  71 repeating the command with each argument (e.g. `bbcmd select:<file1>
  72 select:<file2> ...`).
  73 
  74 Note: for numeric-based commands (like scroll), the number can be either an
  75 absolute value or a relative value (starting with `+` or `-`), and/or a percent
  76 (ending with `%`). Scrolling and moving, `%` means percent of screen height,
  77 and `%n` means percent of number of files (e.g. `+50%` means half a screen
  78 height down, and `100%n` means the last file)
  79 
  80 ## Globbing
  81 
  82 `bb` uses glob patterns to determine which files are visible. By default, the
  83 pattern is `*`, which means all files except those starting with a `.` (dot).
  84 `bb`'s globs are POSIX-compliant and do not support bash-style extensions like
  85 `**` for recursive matches. `bb` supports multiple, space-separated globs, so
  86 for example, you can display all files including dotfiles with the glob: `.* *`
  87 (by default, pressing the `.` key will toggle this behavior). The current `bb`
  88 glob is available in `$BBGLOB`, which can be used in scripts if left unquoted.
  89 
  90 ## Final Notes
  91 
  92 Internally, `bbcmd` writes the commands (`NULL` terminated) to a file whose path is
  93 in`$BBCMD` and `bb` reads from that file when it resumes. These commands can also
  94 be passed to `bb` at startup as command line arugments starting with `+`, and
  95 will run immediately.  E.g. `bbcmd +'col:n' +'sort:+r' .` will launch `bb` only
  96 showing the name column, randomly sorted.
  97 
  98 `bb` also optimizes any scripts that only contain just a `bbcmd` command and no
  99 shell variables, other commands, etc. (e.g. `bbcmd move:+1`) These
 100 `bbcmd`-command-only scripts directly modify `bb`'s internal state without
 101 spawning a shell, so they're much faster and avoid flickering the screen.