From 5a5f9afa05a1f4dfdcd559c0f28691a65bfc6b46 Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Mon, 10 Jun 2019 20:37:34 -0700 Subject: Updated with some cleaner behavior for PICK and added SPIN. Also removed command line flags in favor of manually using `tput rmcup`. Updated the documentation. --- README.md | 103 +++++++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 75 insertions(+), 28 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index cc67312..b961f2a 100644 --- a/README.md +++ b/README.md @@ -8,22 +8,81 @@ - Without any build dependencies other than the C standard library (no ncurses) - A good proof-of-concept for making a TUI from scratch -The core idea behind `bb` is that almost all actions are performed by piping -selected files to external scripts, rather than having the file manager itself -try to anticipate and hard-code every possible user action. Unix tools are very -good at doing file management, the thing that `bb` adds is immediate visual -feedback and rapid navigation. - -For example, instead of using `ls`, then `rm` and typing out file names, you can -just open `bb`, scroll through the list of files, select the ones you want to -delete, and hit `D`. The `D` key's behavior is defined in a single line of code -in `config.h` as passing the selected files as arguments to `rm -rf "$@"`. -That's it! If you want to add a mapping to upload files to your server, you can -just add a binding for `scp user@example.com:~/ "$@"`. Want to zip files? Add -a mapping for `read -p "Archive: " name && zip "$name" "$@"` or, if you have -some complicated one-time task, you can just hit `>` to drop to a shell and run -commands with the selected files available in `$@` (or use `|` to run a quick -one-liner command that gets the selected files piped as input). +## Building +No dependencies, just: + +`make` +`sudo make install` + +## Usage + +Run `bb` to launch the file browser. `bb` also has the flags: + +- `-d`: when `bb` exits successfully, print the directory `bb` was browsing. +- `-s`: when `bb` exits successfully, print the files that were selected. +- `-0`: use NULL-terminated strings instead of newline-separated strings with + the `-s` flag. + +Within `bb`, press `?` for a full list of available key bindings. In short: +`h`/`j`/`k`/`l` or arrow keys for navigation, `q` to quit, `` to toggle +selection, `d` to delete, `c` to copy, `M` to move, `r` to rename, `n` to +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 +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 +put the following function in your `~/.profile` (or `~/.bashrc`, `~/.zshrc`, +etc.): + + function bcd() { cd "$(bb -d "$@" || pwd)"; } + +For [fish](https://fishshell.com/) (v3.0.0+), you can put this in your +`~/.config/fish/functions/`: + + function bcd; cd (bb -d $argv || pwd); end + +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 +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 +above). For sh and bash, put this in your `~/.profile`: + + bind '"\C-b":"bcd\n"' + +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. @@ -44,18 +103,6 @@ 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. -## Building - -`make` -`sudo make install` - -## Usage - -Just run `bb` to launch the file browser. Press `?` for a full list of -available key bindings. In short: `h`/`j`/`k`/`l` or arrow keys for navigation, -`q` to quit, `` to toggle selection, `d` to delete, `c` to copy, `M` to -move, `r` to rename, `n` to create a new file, `N` to create a new directory, -and `|` to pipe files to a command. ## Hacking -- cgit v1.2.3