patch to add toke_scan_str options

This is a reimplementation of the [original patch](http://github.com/rafl/devel-declare/pull/1) which enhances the existing API rather than creating a new function. Tests and documentation have been updated and expanded.