Initial commit

I was dumb and didn't start committing as soon as I started. vgstash is
considered ready for 0.1 and beta usage. There's a somewhat long road
ahead, but I look forward to making this tool finally come to fruition.

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.