From e1cdee8d22036c14c493952145a741d3831fd4ad Mon Sep 17 00:00:00 2001
From: Phil <phil@grmr.de>
Date: Fri, 10 Nov 2017 20:05:07 +0100
Subject: [PATCH] Improve documentation
---
README.md | 36 +++++++++++++++++++++++++++++++-----
src/parser.rs | 1 +
2 files changed, 32 insertions(+), 5 deletions(-)
diff --git a/README.md b/README.md
index 1d00e55..73fc9c4 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,39 @@
Rust implementation of [golang challenge #1](http://golang-challenge.org/go-challenge1).
-A simple binary fileformat for a drum machine is given. The task is to reverse
+A simple binary file format for a drum machine is given. The task is to reverse
it and implement a decoder it.
-## ToDo
+## File format
-- [ ] write example cli that pretty prints the fixture's contents
-- [ ] create documentation/tutorial/walkthrough and give it to `nom` community
- - [ ] describt binary format (result of re)
+There is no real specification. But this is my understanding based on looking
+at the provided example files and reading the challenge description.
+
+A file starts with a header and is followed by multiple lines. All numbers are
+encoded with big endianness.
+
+### Header
+
+Size | encoding | Description
+-----|----------|------------
+ 6 | ASCII | magic bytes "SPLICE"
+ 8 | u64 | file size (bytes _after_ this field are counted)
+32 | ASCII | version string (of the editor used to create the file?)
+ 4 | f32 | tempo
+
+### Line
+
+Size | Encoding | Description
+-----|----------|----------------
+ 1 | u8 | id
+ 4 | u32 | length of the name field (n_l)
+ n | ASCII | name
+16 | bool[] | data (encoded as information when to hit)
+
+## To-do
+
+- [ ] write example CLI that pretty prints the fixture's contents
+- [ ] create documentation / tutorial / walk through
- [ ] describe implementation steps
- [ ] maybe add something (tests!?) that allows for better/easier debugging
+ - [ ] find out how to properly debug
diff --git a/src/parser.rs b/src/parser.rs
index ea613c8..0c5997b 100644
--- a/src/parser.rs
+++ b/src/parser.rs
@@ -46,6 +46,7 @@ named!(parse_pattern<&[u8], Pattern>,
// ignore all unused bytes at the end
IResult::Done(_,pattern) => pattern,
// XXX: what type of input could trigger this?
+ // -> uncommon values in file length?
// TODO: make it not panic and handle it gracefully
// TODO: add extra testcase, that triggers this path
_ => panic!("this should never be reached")
--
GitLab