add shell integration guide

Author: facundoolano

README.md

@@ -30,10 +30,11 @@ The binary should be available as `rpg-cli` (assuming you have `~/.cargo/bin` in
 If you use nix/nixos you can get rpg-cli from nixpkgs, either install it by adding it to your system config, installing it with `nix-env -i rpg-cli` or try it in a ephemeral shell with `nix-shell -p rpg-cli`.
 Note that at the current time of writing, the package hasn't hit any of the channels yet. When you try it, check that it's in your channel.
 
-### Use as a cd replacement (recommended)
+### Shell integration (recommended)
 
-Once the binary is installed with one of the methods described above, it can be wrapped on a shell function or alias
-so the working directory is updated to track to the hero's progress. You can set that up by adding something like this to your `.bashrc`:
+The game is designed to integrate with common file system operations, such as changing directories or deleting files.
+
+The most basic type of integration consists in wrapping rpg-cli in a shell function, such that the working directory is updated to track to the hero's progress, effectively working as a `cd` alternative:
 
 ```sh
 rpg () {
@@ -42,8 +43,6 @@ rpg () {
 }
 ```
 
-This assumes `rpg-cli` is in your path, update with the specific location if not. You can `source ~/.bashrc` to apply the change without opening a new shell.
-
 Or, if you want to go all the way and *really* use it in place of `cd`:
 
 ```sh
@@ -53,21 +52,16 @@ cd () {
 }
 ```
 
-If you use fish shell, update `~/.config/fish/config.fish` instead:
-
-```fish
-function rpg
-    rpg-cli $argv
-    cd (rpg-cli --pwd)
-end
-```
+Other commands like `rm`, `mkdir`, `touch`, etc. can also be aliased. Check the [shell integration guide](shell/README.md) for more sophisticated examples, as well as their fish shell equivalents.
 
 ### Troubleshooting
 
 * The release binary for macOS [is not signed](https://github.com/facundoolano/rpg-cli/issues/27). To open it for the first time, right click on the binary and select "Open" from the menu.
 
 ## Usage
 
+This example session assumes a basic `rpg` function as described in the previous section.
+
 The first time you run the program, a new hero is created at the user's home directory.
 
     ~ $ rpg

shell/README.md

@@ -0,0 +1,83 @@
+# Shell integration
+
+To get the most out of rpg-cli, it is suggested to define aliases or wrapper functions so the game can be integrated into a regular shell session, with enemies appearing along the way.
+
+This guide describes the basic building blocks to write such functions and shows some examples.
+
+## Basic `cd` alternative
+
+The default rpg-cli command works as `cd`, changing the hero's location from
+one directory to another. Since the program itself can't affect your shell session,
+you need to write a function so the working directory is changed to match that of the hero:
+
+```sh
+rpg () {
+    rpg-cli "$@"
+    cd "$(rpg-cli --pwd)"
+}
+```
+
+This assumes `rpg-cli` is in your path, update with the specific location if not. You can define it directly in your current session, add it to `~/.bashrc`, source it from another script, etc.
+
+If you use fish shell, update `~/.config/fish/config.fish` instead:
+
+```fish
+function rpg
+    rpg-cli $argv
+    cd (rpg-cli --pwd)
+end
+```
+
+## Full `cd` override
+
+If you like having enemies popping up while using `cd`, you can override that instead of using a separate function:
+
+```sh
+cd () {
+    rpg-cli "$@"
+    builtin cd "$(rpg-cli --pwd)"
+}
+```
+
+## Custom integration commands
+
+To better adapt for different usage patterns, finer-grained commands are provided:
+
+* `rpg-cli --mv <path>` will set the hero's location to `<path>` without initiating battles.
+* `rpg-cli --pwd` will print the hero's current location.
+* `rpg-cli --battle` will initiate a battle with a probability that changes based on the distance from home. If the battle is lost the exit code of the program will be non-negative.
+
+## Prevent intermediate battles
+
+Note that the logic of the default rpg command is this: the hero moves one directory at a time, and enemies can appear at each step:
+
+* If the hero dies, the game is restarted and you go back home.
+* If the hero wins the battle, it will stop at the battle's location instead of keep moving to the initial destination. The rationale for this behavior is that you may need to adjust your strategy after each battle: use a potion, return home, try to escape battles, etc.
+
+Having `cd` not consistently set the pwd to the intended destination may not be acceptable if the program is used casually while doing other work.
+A better alternative for this usage pattern is enabled by the other integration commands, for example:
+
+```sh
+cd () {
+    builtin cd "$@"
+    rpg-cli --mv .
+    rpg-cli --battle
+}
+```
+
+## Aliasing other commands
+
+Another way to use rpg-cli is to initiate battles when attempting to execute file-modifying operations. Only when the battle is won the operation is allowed:
+
+```sh
+alias rpg-battle="rpg-cli --mv . && rpg-cli --battle"
+
+alias rm="rpg-battle && rm"
+alias rmdir="rpg-battle && rmdir"
+alias mkdir="rpg-battle && mkdir"
+alias touch="rpg-battle && touch"
+alias mv="rpg-battle && mv"
+alias cp="rpg-battle && cp"
+alias chown="rpg-battle && chown"
+alias chmod="rpg-battle && chmod"
+```