aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorzlg <zlg@zlg.space>2018-10-18 20:22:21 -0700
committerzlg <zlg@zlg.space>2018-10-18 20:22:21 -0700
commit1518ccd7f43724a8f6f4b7024d875a78b5e0c9de (patch)
tree4f4fd30e8fcc104f6b196fc05be91d63e6f98c25
parentcli: Tell the user when a game lacks notes (diff)
downloadvgstash-1518ccd7f43724a8f6f4b7024d875a78b5e0c9de.tar.gz
vgstash-1518ccd7f43724a8f6f4b7024d875a78b5e0c9de.tar.bz2
vgstash-1518ccd7f43724a8f6f4b7024d875a78b5e0c9de.tar.xz
vgstash-1518ccd7f43724a8f6f4b7024d875a78b5e0c9de.zip
README: expand on usage, cover shell quoting
Diffstat (limited to '')
-rw-r--r--README.md106
1 files changed, 99 insertions, 7 deletions
diff --git a/README.md b/README.md
index 5d42320..a11163c 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,7 @@ player:
* digital
* both
* Progress
+ * unbeatable
* new
* playing
* beaten
@@ -61,6 +62,8 @@ vgstash tracks it somewhat like this:
This is the bare minimum information you need to meaningfully track a video
game in your collection.
+# Command Line Usage
+
vgstash comes with a command line client of the same name, which gives you
high level commands to manipulate the database with. It's the reference
implementation for a vgstash client.
@@ -72,25 +75,114 @@ $ vgstash add 'FTL: Faster Than Light' Steam d n
Added FTL: Faster Than Light for Steam. You digitally own it and you have not started it.
```
-Pretty easy, huh? Each game and system added to vgstash is free-form and can
-be tuned to match the user's preferences. vgstash has a fairly small set of
-commands:
+Pretty easy, huh? Each game and system added to vgstash is free-form and can be
+tuned to match the user's preferences.
+
+## Quoting Game Titles
+
+A note on characters: some shells treat certain characters differently. The most
+common ones you'll run into are punctuation, like single quotes ('), double
+quotes (") and exclamation points (!). You'll need to search your shell's manual
+for "character escaping" to get the details.
+
+Let's take a few game titles that might be problematic for a shell, and add them
+to vgstash. These examples assume you're using bash (the Bourne Again SHell) or
+something comparable.
+
+First: a title with single quotes and exclamation points:
+
+```bash
+$ vgstash add "Eek! It's a Bomb!" Android d n
+```
+
+Double quotes are useful for quoting just about any game title.
+
+Next is a little more insidious: a title with two (or more) exclamation points:
+
+```bash
+$ vgstash add 'Mario Kart: Double Dash!!' GCN p n
+```
+
+Note that we're using single quotes; if we used double quotes, then the `!!`
+would expand to the last command entered into the shell, creating `Mario Kart:
+Double Dash<your last command here>`. Quite different from what you'd expect!
+
+But what if we, somehow, had both single quotes *and* sequential exclamation
+points? Single-quoted strings cannot escape a single quote character. Double
+quotes won't stop the `!!` expansion. Escaping the exclamation points retains
+the backslash; what is one to do? There are a few ways to tackle this one:
+
+```bash
+# The easy way
+$ vgstash add $'Some title\'s crazy!!' PC d n
+
+# The hard way
+$ vgstash add Some\ title\'s\ crazy\!\! PC d n
+
+# The exotic way
+$ vgstash add "Some title"\''s crazy!!' PC d n
+```
+
+The `$'text'` form is handy when you need to use double and/or single quotes
+alongside exclamation points, or you can just escape every special character
+(including space) as needed.
+
+The "exotic" one takes advantage of the shell's built-in string concatenation
+and the ability to mix quoting styles. First we have `Some title` in double
+quotes; then an escaped single quote for literal output; then `s crazy!!` in
+single quotes to avoid the `!!` expansion.
+
+The last option is to disable the feature (history expansion) altogether, though
+you'll miss out on nice stuff like `sudo !!`. In bash, it's disabled with `set
++H` or `set +o histexpand`. Change `+` to `-` to turn it back on when you're
+done.
+
+These tips may not work in all shells, so try using `echo` to print the title
+you want before trying to add it in vgstash! If you accidentally add a game this
+way, copy the title that's output in the success message and paste it into your
+delete command:
+
+```bash
+# Let's say I used 'ls' last
+$ vgstash add "my game!!" PC d n
+Added my gamels for PC. You own it digitally and it's new.
+$ vgstash delete "my gamels" PC
+Removed my gamels for PC from your collection.
+```
+
+That's it! This is something that the shell does before vgstash begins
+processing its arguments, so please don't report any bugs dealing with quoting.
+
+# Commands
+
+vgstash has a fairly small set of commands:
* add
* delete
-* update
+* export
+* import
* list
+* notes
+* update
The power is in the `list` command. vgstash comes with a set of default filters
that allow you to reason about your game collection. For example, this command
will show you every game marked "playing" that you also own in some way:
```bash
-$ vgstash list playlog
-# listed output here
+$ vgstash list -w 40 playlog
+Title | System | Own | Progress
+----------------------------------------
+Crashmo | 3DS | D | P
+Ever Oasis | 3DS | P | P
+Fire Emblem | 3DS | P | P
+Monster Hun | 3DS | D | P
+Box Pusher | DSi | D | P
+Glow Artisa | DSi | D | P
+Dark Souls | PS3 | P | P
```
-Consult `vgstash -h` for further usage information.
+Consult `vgstash --help` for further usage information.
# Roadmap