I don't like the current hinting system nor your proposed improvement that hides the information and relies on a cabal to pre-compute the hints so that the unwashed masses never have to see it, know about it, or use it. I think such hidden information has a high probability to be incomplete and inconsistent such that users become very surprised why something works fine on one system and looks identical and doesn't work on some other system.

But I think you can greatly simplify the hints to the point that making them visible is not a burden.

I would define the following defaults:

And I would define the following options:

  1. This function always returns just one scalar, even when used in a list context (represented by $, the sigil for scalar values in Perl 5)
  2. Empty string (including undef) means failure (represented by ", not only unambiguously "string"y in Perl but also visually similar to '', the empty string)
  3. 'False' means failure (represented by !, logical negation)

Then you can quite concisely represent any meaningful combination of those options: 

use autodie qw( ReadLine Copy!$ NextKeyword! GetParam$ GetCount"$ Next
+Word" );

[download]

Where ReadLine() returns an empty list on failure, undef in a scalar context. Copy() always returns a scalar which is simply false in the case of failure. A successful NextKeyword() returns either a non-empty list or (in scalar context) a string that is never '' nor '0'. GetParam() does return undef; on failure. GetCount() returns an empty string for failure. Finally, a successful NextLabel() returns either a non-empty list or (in scalar context) a string that is not ''.

As for pre-computing hints, I would require that the user request the pre-computed hint so that, if the current system lacks that particular hint, the user can be made aware of the problem. I'd probably use a '?' to indicate that the user doesn't claim to know the answer and asks that the module author provide it.

- tye        

In reply to Re: RFC: User subroutine hinting interface for autodie (terse, unhidden) by tye
in thread RFC: User subroutine hinting interface for autodie by pjf

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.