Add `@impl or_none` to try_scan! (#28)

[kangalio]

This is my attempt at implementing #28

[oli-obk]

Cool! Please also add a test to our test suite showing a use of it

[kangalio]

I added a test, and also documented this new feature.

On another note, the following two macro variants seem to be more of an implementation detail than a part of the public API

(@question_mark: $($e:tt)+) => { ... };
(@unwrap: $($e:tt)+) => { ... };

Do you agree that these two macro variants should be removed from the docs?

[oli-obk]

All of the @foo patterns are meant to be internal. You're not supposed to invoke them directly, but there should be convenient wrappers for them.

[oli-obk]

For example: the scan! macro invokes the @impl unwrap variant. So I don't think we should be exposing these variants in the documentation. We can add a scan_opt! macro that invokes try_scan with @impl or_none

[kangalio]

It is a very convenient feature to be able to choose how errors will be handled. I'd personally pledge for exposing the @impl ... feature. Maybe it can be renamed to just @... or something else entirely, in order to make it more intuitive and approachable to users.

If you disagree, I suppose a wrapper macro is also a viable option.

[oli-obk]

hmm... I like that. So we get rid of the impl and just use @mode for choosing one of the modes.

[oli-obk]

We should probably rename the modes to something more user friendly then. What do you think about the following list?

• @unwrap or @panic
• @return_err or @?
• @option

[oli-obk]

at that point we could also start supporting these flags directly on scan! instead of try_scan!

[kangalio]

@unwrap or @panic @return_err or @? @option

Those look like good ideas. Let me add my own:

@unwrap or @panic @return_err or @? @return_none or @option or @or_none

If I had to choose one each, hmm... I think I would choose @panic + @return_err + @return_none. Those are very clear names because they describe exactly what is gonna happen on failures.

[oli-obk]

I'm not sold on the capitalization of panic as Panic, but other than that, I agree with your selection, those keywords make it very clear.

[kangalio]

Oh I'm only seeing now that GitHub capitalized my panic. It was supposed to be lowercase