Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight

Comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

Honourable monks,

I have often the same problem when using complex data structures (HoH, HoA, generally /([HA]o)+[HA]/): when passing data structures to functions or returning data structures, how do you document the form of data to the user of the function?

Perhaps the problem is an indication of the ad hoc nature of the data structures, but suppose you have a function that returns

  • an ID number and a numerical value for that ID number as a hash key and value
  • which are hashes under the hash keys 'changes' and 'originals'
  • with the mean and variance for both under hash keys 'means' and 'variances', which are arrays
  • and all these being an item in an array of similar hashes.

Now, one way I am inclined to document this would be to use straight Perl syntax in describing an "abstracted" item in the data structure, meaning that the parts that can vary are variables:

[ { originals => { $id => $val, ... }, changes => { $id => $val, ... }, means => [ $originals_mean, $changes_mean ], variances => [ $originals_variance, $changes_variance ], }, ... ]

Here the ellipsis means that the substructure contains identical entries where the parameterized parts (variables) vary. Literal names or values would be just those: literals. The benefit of this is that you can now refer to particular values in the data structure simply by using the variable name (such as $id) in describing what they actually contain. Another benefit is that you can use this "template" in traversing the data structure or accessing values.

However, given complex enough data structures, this will be unwieldy to both write and read. Besides this, unless the values are identical in the above, $val should in fact be two different variables, signifying that they do not depend on each other (while $id could be the same, since the same values occur in both 'changes' and 'originals' hashes). Larger data structure means that there will be even more points where you must name the varying values.

Surely there must be better ways. How do you do it?

print "Just Another Perl Adept\n";

In reply to How to document complex data structures? by vrk

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, 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, 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.
  • Log In?

    What's my password?
    Create A New User
    [Corion]: marioroy: Oh, that's always cool, having API-compatible modules. This makes testing and comparing things much easier
    [marioroy]: IPC in MCE::Shared can handle 400k (sends) per second. That's seems a lot for being a pure-Perl module. After making the release, will come back and post a solution for a node by a fellow wanting faster logging.
    [Corion]: While working on WWW::Mechanize:: Chrome, I had the suspicion that AnyEvent was doing something wrong, but I was able to swap it out for Mojolicious and the error persisted.
    [Corion]: Of course, the error was in my own code ;)
    [marioroy]: Corion, start and start_child in MCE::Hobo::Manager return a MCE::Hobo object, whereas P::FM returns the PID. I can have it return the PID though. I tried Hobo::Manager with several P::FM modules, just changed P::FM to MCE::Hobo::Manager and it works.
    [marioroy]: I also have a Hobo driver for Forklift allowing folks to use in multiple classes, no conflicts with one another. That's not possible for P::FM.
    [Discipulus]: congrats marioroy!
    [marioroy]: CORE::wait works well eventhough multiple instances or classes using Hobo::Manager.
    [Corion]: marioroy: I'm not sure what the normal use for the PID is in P:FM, but I guess that most programs just ignore or log it
    [Corion]: Oh, yes, programs could call wait $pid, but if your $pid is an object, then you could add a ->wait method to it and wait $pid would call that automatically "thanks" to indirect object notation

    How do I use this? | Other CB clients
    Other Users?
    Others lurking in the Monastery: (6)
    As of 2017-05-26 08:40 GMT
    Find Nodes?
      Voting Booth?