updated internal code with tests, and slightly improved error reporting
merged readme