Helping EPIC guess types tip

  • Gordon Hutchison

    I have found that if you have a bless reference coming
    in to a sub the following comment will help EPIC guess the

    # Get the parameter and tell EPIC the type
    my $obj = shift;       # $obj = OurProduct::MyClass::

    $obj->[Ctrl-Space here will bring the correct methods up for the MyClass type]

    I do not know if this is a feature or just a side-effect
    of the implementation that already works to pick up
    the type from my $obj = Class::new() but I thought I would share it -
    perhaps also in the hope that it does not go away.

    Any other such tips?

    (e.g. I am just about to look at customising perldoc)


    • Jan Ploski

      Jan Ploski - 2008-11-10

      This is a side effect of the implementation. It has been in EPIC for years now, so on that basis you may assume it won't go away (no guarantees though).

      Regarding perldoc, I agree that it would be nice to have a convention to aid EPIC (and programmers) in type recognition, but I am unaware of anything that one could call an established standard. This is perhaps due to the general philosophy of perldoc as a free-form, between-the-lines, reader-friendly description rather than a semi-formal tool-friendly specification.

      Personally, I don't use perldoc, but instead rely on Javadoc-like syntax conventions, e.g.

      # Find the birth date for a given person
      # @param name   name of a person
      # @param id     (optional) person's id
      # @return birth date in format yyyy-mm-dd
      sub get_birthday
          my $name = shift;
          my $id = shift;


         return $birthday;

      This convention obviously contains no type information, but it could be inserted in front of the parameter's name after @param, for example. Then it could be picked up by EPIC (other features which can use such description is hover-on documentation and parameter completion). However, an additional problem is hash-style parameter passing (where the keys of a hash are the actual items that need documenting), which of course can be done in two ways ({ param => value } or just param => value) and mixed with normal positional parameters.

      Of course the downside of such Javadoc-like conventions is that the standard perldoc tool no longer applies.

      Perl 6 type annotations could also become a possible basis, but who knows when Perl 6 will be released and widely available.

      If you come up with a really good set of conventions, I encourage you to write them up (maybe first checking around the web what other people have invented), and the specification could be implemented in EPIC some day.


Log in to post a comment.