add proper exception handling for invalid locations

Also adds an example on how to use it.
simplify apply_file function

apply_file() will now guess from the implemented functions, which entities
to read from the file and which handlers to apply.