From 792a39500ce926751f663eb54d2b58e3ed6fd427 Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Mon, 10 Jun 2019 22:26:13 -0700 Subject: Simplified the make flags for fuzzy finding and asking. Cleaned up the readme a bit. --- README.md | 99 +++++++++++++++++++++++++++------------------------------------ 1 file changed, 43 insertions(+), 56 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b961f2a..b11926f 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,47 @@ create a new file, `N` to create a new directory, `:` to run a command with the selected files in `$@`, and `|` to pipe files to a command. Pressing `Ctrl-c` will cause `bb` to exit with a failure status and without printing anything. -## Using bb to Change Directory +# bb's Philosophy +The core idea behind `bb` is that `bb` is a file **browser**, not a file +**manager**, which means `bb` uses shell scripts to perform all modifications +to the filesystem (passing selected files as arguments), rather than +reinventing the wheel by hard-coding operations like `rm`, `mv`, `cp`, `touch`, +and so on. Shell scripts can be bound to keypresses in config.h (the user's +version of [the defaults in config.def.h](config.def.h)). For example, `D` is +bound to `rm -rf "$@"`, which means selecting `file_foo` and `dir_baz`, then +pressing `D` will cause `bb` to run the shell command `rm -rf file_foo dir_baz`. + +## Customizing bb +`bb` comes with a bunch of pre-defined bindings for basic actions in +[config.def.h](config.def.h) (within `bb`, press `?` to see descriptions of the +bindings), but it's very easy to add new bindings for whatever custom scripts +you want to run, just add a new entry in `bindings` in config.h with the form +`{{keys...}, "", ""}` The description is shown when +pressing `?` within `bb`. + +### User Input in Scripts +If you need user input in a binding, you can use the `ASK(var, prompt, +initial)` and `ASKECHO(prompt, initial)` macros, which internally use the +`read` shell function (`initial` is discarded) or the `ask` tool, if `USE_ASK` +is set to 1. This is used in a few key bindings by default, including `n` and +`:`. + +### Fuzzy Finding +To select from a list of options with a fuzzy finder in a binding, you can use +the `PICK` macro. During the `make` process, you can use `PICKER=fzy`, +`PICKER=fzf`, or `PICKER=ask` to choose which fuzzy finder program `bb` will +use (and provide some default arguments). This is used in the `/` and `Ctrl-f` +key bindings by default. + +### API +`bb` also exposes an API that allows shell scripts to modify `bb`'s internal +state. To do this, call `bb +` from within `bb`. For example, by +default, `j` is bound to `bb '+move:+1'`, which has the effect of moving `bb`'s +cursor down one item. More details about the API can be found in [the config +file](config.def.h). + +## FAQ +### Using bb to Change Directory Applications cannot change the shell's working directory on their own, but you can define a shell function that uses the shell's builtin `cd` function on the output of `bb -d` (print directory on exit). For bash (sh, zsh, etc.), you can @@ -47,7 +87,7 @@ For [fish](https://fishshell.com/) (v3.0.0+), you can put this in your In both versions, `|| pwd` means the directory will not change if `bb` exits with failure (e.g. by pressing `Ctrl-c`). -## Launching bb with a Keyboard Shortcut +### Launching bb with a Keyboard Shortcut Using a keyboard shortcut to launch `bb` from the shell is something that is handled by your shell. Here are some examples for binding `Ctrl-b` to launch `bb` and change directory to `bb`'s directory (using the `bcd` function defined @@ -59,58 +99,5 @@ For fish, put this in your `~/.config/fish/functions/fish_user_key_bindings.fish bind \cB 'bcd; commandline -f repaint' -# bb's Philosophy -The core idea behind `bb` is that `bb` is a file **browser**, not a file -**manager**, which means `bb` uses shell scripts to perform all modifications -to the filesystem (passing selected files as arguments), rather than -reinventing the wheel by hard-coding operations like `rm`, `mv`, `cp`, `touch`, -and so on. Shell scripts can be bound to keypresses in config.h (the user's -version of [the defaults in config.def.h](config.def.h)). For example, `D` is -bound to `rm -rf "$@"`, which means selecting `file_foo` and `dir_baz`, then -pressing `D` will cause `bb` to run the shell command `rm -rf file_foo dir_baz`. - -`bb` comes with a bunch of pre-defined bindings for basic actions in -[config.def.h](config.def.h) (within `bb`, press `?` to see descriptions of the -bindings), but it's very easy to add new bindings for whatever custom scripts -you want to run, just add a new entry in `bindings` in config.h with the form -`{{keys...}, "", ""}` The description is shown when -pressing `?` within `bb`. - -## User Input in Scripts -If you need user input in a script, you can just use the `read` shell function -like so: `read -p "Archive: " name && zip "$name" "$@"` However, `read` doesn't -support a lot of functionality (e.g. using the arrow keys), so I would recommnd -using [ask](https://bitbucket.org/spilt/ask) instead. If you have `ask` -isntalled, making `bb` will automatically detect it and the default key -bindings will use it instead of `read`. - -## API -`bb` also exposes an API so that programs can modify `bb`'s internal state. -For example, by default, `f` is bound to `bb "+goto:$(fzf)"`, which has the -effect of moving `bb`'s cursor to whatever `fzf` (a fuzzy finder) prints out. -More details about the API can be found in [the config file](config.def.h). - -## Zero Dependencies - -There's a lot of TUI libraries out there like ncurses and termbox, but -essentially all they do is write ANSI escape sequences to the terminal. `bb` -does all of that by itself, just using basic calls to `write()`, with no -external libraries beyond the C standard library. Since `bb` only has to -support the terminal functionality that it uses itself, `bb`'s entire source -code is less than half the size of the source code for an extremely compact -library like termbox, and less than *half a percent* of the size of the source -code for ncurses. I hope anyone checking out this project can see it as a great -example of how you can build a full TUI without ncurses or any external -libraries as long as you're willing to hand-write a few escape sequences. - - -## Hacking - -If you want to customize `bb`, you can add or change the key bindings by -editing `config.h` and recompiling. In [suckless](https://suckless.org/) style, -customizing means editing source code, and compilation is extremely fast. -Key character constants are in `keys.h` and the rest of the code is in `bb.c`. - -## License - +# License `bb` is released under the MIT license. See the `LICENSE` file for full details. -- cgit v1.2.3