improved the API and added some tests and examples (still more to add)