Clean up and docs

[TheOtterlord]

Hello.

As I am still learning rust, I have not done any parsing yet. I'm just getting use to the project structure and will hopefully begin parsing soon.

This PR adds a few things including documentation for development and for usage.

• I've re-written the README file to add more information including your roadmap from the OSI issue.
• I've added a docs folder to hold all documentation for usage and for development. Check out my fork if you want a closer look.
• I also added an example.gpl file. You specified an example file in main, but there was no such file and so running cargo run always failed. I thought I'd add a file that contains all currently implemented components. This way, we can use cargo run to get access to the token stream etc...
• I think I've added a test or two, and I have also renamed some of yours. My reasoning is that if we are testing a certain feature, for example functions, we can call cargo test function and run all function tests.

I've run our tests and currently we have 13 tests that resolve as follows.

running 12 tests
test tests::test_empty ... ok
test tests::test_function_call_with_args ... ok
test tests::test_function_with_arg ... ok
test tests::test_function_empty ... ok
test tests::test_function_call ... ok
test tests::test_function_with_args ... ok
test tests::test_function_with_arg_and_result ... FAILED
test tests::test_function_with_result ... FAILED
test tests::test_functions_empty ... ok
test tests::test_variable ... FAILED
test tests::test_variable_string_with_spaces ... FAILED
test tests::test_variables ... FAILED

I'm happy to write more documentation if you think something is missing. Feel free to change anything you think I've messed up.

[mjarkk]

Looking good!

[mjarkk]

Maybe something nice next would be to add tests that we expect the code to fail to compile like when we use let in the global scope.

The parse_str function has .unwrap() at the end and the unwrap function expects the value to be Ok if not it will panic.
Maybe add an extra function like parse_str_fail and inside the function do something like this:

1. place the pared output in a variable: let res = Parse::par... without the unwrap because we expect a failure
2. Using an if let Ok(parsed_result) = ... statement check if the response is Ok (if let documentation, Result documentation)
3. Inside the if statement do a panic with an error message and the parsed output so we know the parse result for debugging
   1. Write a panic with an error message documentation
   2. Make the panic message dynamic by using format documentation (format is generally used to "build" strings)
   3. Add the parsed_result to the message
      1. To do this we need to derive Debug Parser struct because otherwise it's not printable (for an example see the Function struct)
      2. Add the parsed_result to the message by using {:?} instaid of {} the {:?} is for printing debug information, {} is for printing the (Display)[https://doc.rust-lang.org/std/fmt/trait.Display.html] trait and the display trait should generally pretty print data.

[TheOtterlord]

Sure.

Tests like this will be really useful to make sure we do not parse any invalid code accidently. I'll have a go at that now.

Let me know if there are any other cases you think I should cover.