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 ],
  },
  ...
]
[download]

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?

---

---

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! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

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:
	&		&
	<		&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.