allow public uses of structs; add sample program

README.md

@@ -4,6 +4,51 @@ a library for parsing Bitsy game data.
 
 the version number follows Bitsy itself, so version 0.65.* targets Bitsy 6.5.
 
+## how to use
+
+this sample program converts the player avatar to a smiley face.
+```rust
+extern crate bitsy_parser;
+use std::{env, fs};
+use bitsy_parser::game::Game;
+use bitsy_parser::image::Image;
+
+/// replaces the player avatar with a smiley face.
+fn main() {
+    let input_file = env::args().nth(1)
+        .expect("No game data specified. Usage: `invert infile outfile`");
+    let output_file = env::args().nth(2)
+        .expect("No game data specified. Usage: `invert infile outfile`");
+
+    let mut game = Game::from(fs::read_to_string(input_file).unwrap());
+
+    game.avatar.animation_frames = vec![
+        Image {
+            pixels: vec![
+                0,0,1,1,1,1,0,0,
+                0,1,1,1,1,1,1,0,
+                1,1,0,1,1,0,1,1,
+                1,1,0,1,1,0,1,1,
+                1,1,1,1,1,1,1,1,
+                1,1,0,1,1,0,1,1,
+                0,1,1,0,0,1,1,0,
+                0,0,1,1,1,1,0,0,
+            ]
+        }
+    ];
+
+    fs::write(output_file, &game.to_string())
+        .expect("Failed to write to output file");
+}
+```
+
+some more practical uses would be things like:
+
+* remove duplicate tiles
+* merge two Bitsy games together
+* programmatically create Bitsy games
+* a Bitsy game editor
+
 ## todo
 
 ### failing tests
@@ -13,7 +58,3 @@ test_room_from_string shows an unexpected ordering for the items in the output o
 ### tidy up
 
 * refactor the more shonky bits to idiomatic rust
-
-### documentation
-
-examples of use cases (dedupe tiles, merge games, etc.)