diff options
Diffstat (limited to 'README.mdown')
| -rw-r--r-- | README.mdown | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/README.mdown b/README.mdown new file mode 100644 index 0000000..7d617c6 --- /dev/null +++ b/README.mdown @@ -0,0 +1,257 @@ +vgstash is a tool used to keep track of a video game collection. In addition to +basic inventory maintenance, vgstash supports the ability to clarify whether or +not the user owns a game, and their progress through said game. This makes it +easy to manage a backlog and serve as a "memory" for which games someone has +finished. + +# Concept + +Essentially, vgstash just gets out of your way and lets you manage things. +Nothing fancy like box art or finding games in a massive dropdown box. There are +easy flags to track common searches, like "All games that are owned and haven't +been beaten", making vgstash convenient. + +Since vgstash itself is just a front-end to an SQLite dataabase, other +interfaces to this basic database format can be built to extend the basic +concept. SQLite is supported across tons of languages and platforms, so it's +rather trivial to build another frontend to it. If that's not enough, vgstash +also supports exporting collections as YAML or pipe-delimited lines, and +importing from YAML. This makes batch-editing by a human easy with YAML, and the +raw format is great for pushing vgstash's output through pipes, as any good +\*nix tool should. + +## Data Format + +The key to managing things is keeping it simple, but flexible enough to give you +meaningful insight to the data itself. vgstash gets straight to business +with its data format: + +* Name (string) +* System (string) +* Ownership (boolean) +* Completion Level (integer) + * 0 (Fresh) + * 1 (In Progress) + * 2 (Beaten) + * 3 (Completed) + +There isn't a hard limit on the length of the Name or System strings. SQLite +itself, however, has internal limits. Those limits may differ between platforms, +so there's no guarantee that vgstash databases will work across them. + +# Usage + +Using vgstash is fairly easy, for a command-line program. It accepts +a handful of commands, which will be explained below: + +* init +* add +* update +* delete +* list +* import +* export + +## Tips + +For the sake of accessibility and ease of use, there are some synonyms: + +When specifying ownership, `0` (zero) and `n` mean the same thing. The same is +true of `1` (one) and `y`. + +When specifying progress, the numbers and letters can both be used: + +`0` is also `f` or "fresh". +`1` is also `i` (lowercase I) or "in-progress". +`2` is also `b` (lowercase B) or "beaten". +`3` is also `c` (lowercase C) or "completed". + +Since vgstash relies on the shell and SQLite to function, unquoted strings +are likely to not be handled well. If your data ever looks funky, try correcting +it with a quoted string. Bugs or issues that are reported without quoted strings +will be discarded as WONTFIX, as that's basic, sane practice in every shell +under the sun. + +## Getting Started + +Initialize the database, where your information will be stored: + +~~~ +vgstash init +~~~ + +The location of the database may be set using an environment variable. To learn +more, see the Environment Variables section. + +## Adding + +Next, add a game or two: + +~~~ +vgstash add "Super Mario Bros" NES yes i +~~~ + +In the above example, we're adding *Super Mario Bros* for the NES system. We own +it, and haven't beaten it yet. + +Let's add another: + +~~~ +vgstash add "Borderlands 2" PC +~~~ + +This command has just the basics: game name, and game platform. For the sake of +simplicity, the ownership and progress flags have default values: ownership +defaults to "yes" and progress defaults to "in progress". In both cases, they +are the most typical state for a video game to be added to ones collection. This +can be influenced; see the Environment Variables section for more info. + +## Listing + +vgstash has plenty of methods to interface with your game collection. The +simplest listing would be "list every game in the database": + +~~~ +# The 'all' is optional +vgstash list all +~~~ + +This will output a human-readable list of games you have in the database, with +proper flags and unique IDs, which will come in handy later. For ease of use, +`list all` will sort by system, then by title. Here's an example: + +~~~ +ID | Title | System | Own | Progress +---+---------------------+--------+-----+---------- +3 | Metroid | NES | * | I +1 | Super Mario Bros | NES | | C +2 | The Legend of Zelda | NES | * | B +4 | Borderlands | PC | * | F +~~~ + +From the above output, we can gather that we don't own *Super Mario Bros* +anymore. It's been completed, however, so that's good news. We own *Zelda*, and +it's been beaten, but not completed. We also own *Metroid*, but it's still +in-progress. Lastly, we own Borderlands for the PC, but haven't started playing +it yet. + +The output format is designed to be easy to read, and omits information to serve +as a visual guide whenever possible. From a single glance, you should be able to +spot which games you own and which haven't been started yet. + +### List Filtering + +Seeing all of your games is great when you're just getting started, but what +about after you've added your massive 500 game collection? Nobody wants to sort +through screenfulls of text. That's where filtering comes in. The `list` command +accepts the following filters: + +* **completed** + List games that have been completed. + +* **done** +List games that have been beaten *or* completed. + +* **owned** +List games that you own. + +* **unowned** +List games that you don't own. + +* **wishlist** +List games that you don't own AND are fresh. + +* **incomplete** +List games that have been beaten, but not completed, that you also own. + +* **backlog** +List games that have not been beaten or completed, that you also own. + +## Update + +The `update` command requires the game's ID, the field you're changing, and the +value you're changing it to. + +The fields you can change are + +* title +* system +* ownership +* progress + +As explained in **Data Format**, ownership and progress can use single letters +to substitute for the internal numeric representations. + +To get a game's ID, try using something like `vgstash list | grep "foo"` to find +what you're looking for. + +## Deleting + +For one reason or another, you may need to remove items from your game database. +The `delete` command, coupled with the game's ID, will take care of that for +you. If you want to remove *every* game from your collection, delete the +`.vgstash.db` file from your $HOME directory (or whatever `VGSTASH_DB_LOCATION` +is set to) and start over with `vgstash init`. + +# Environment Variables + +Customization is pretty important if you're going to manage hundreds of games. +There are only a few, but they may come in handy for you! + +* `VGSTASH_DB_LOCATION` + Defaults to `$HOME`. A file named `.vgstash.db` will be found there. + +* `VGSTASH_DEFAULT_OWNERSHIP` + Can be 0 or 1. Default is 1 (yes). + +* `VGSTASH_DEFAULT_PROGRESS` + Can be 0 through 3. Default is 1 (in-progress). + +* `VGSTASH_TABLE_WIDTH` + The width of the table output by the `list` command. For readability +reasons, vgstash will only allow values that are 50 or above. If this variable +is set to zero (0) however, it will expand to fit the entire width of your +terminal/tty. It defaults to 80 characters. + +# Contributing + +vgstash was first written in Python 3.4. There are no plans to produce a Python +2.x version. Patches and pull requests are welcome! However, please do not +contribute to this project unless you are fine with your contributions also +being licensed under the GPL 3.0. This is to simplify licensing issues and keep +things neat. + +Before submitting a Pull Request, please ensure that your commit(s) contain +an addition of your name to the `AUTHORS` file. Others may not use GitHub (or +even git) to get or use vgstash, and every contributor deserves recognition. An +example of what one would add to the `AUTHORS` file is: + +~~~ +John Q. Public, GitHub: @hellomynameisjohn <jqp@genericville.com> + Corrected typos in manpage +~~~ + +Note that the indent is four spaces. + +# Roadmap + +vgstash is considered beta-quality at this time. Please report any issues, bugs, +or even suggestions on how to improve vgstash. + +One feature that will not be built (at least by zlg) is search functionality. +Since vgstash cooperates with piping, it's trivial to pass its output through +other programs and get the fine-grained information a more advanced user may +need. + +Here are the current goals: + +* manpage +* bash-completion file +* refined argument handling for shorthand commands + +# Copyright + +vgstash is Copyright © 2016 Ze Libertine Gamer. It is licensed under the GNU +General Public License, version 3.0. A copy of this license may be found in the +`COPYING` file within this project. It may also be found on the World Wide Web +at http://gnu.org/licenses/gpl-3.0.html. |