If you look at the API of XML::Writer you will see that to create a tag, you make a call like this: 

$writer->startTag('doc', 'version' => '1.0',
                           'status' => 'draft',
                           'topic' => 'AT&T');

[download]
Notice that you pass a single flat list, even though there are two semantic elements being passed - the tag name and the tag's attributes.

In XML::Writer::Nest, I decided to break with this convention (even though the current CPAN version honors it). The reason why

  1. You get the tag name visually distinct from its attributes...
  2. Your API clearly separates arguments that are separate
  3. Passing an array reference is more efficient than pass by value? Help me out here..
  4. Easier to extend. If you decide you need an additional parameter to this sub, then one more positional parm is easy if each original parm is just a scalar. Otherwise, you have to start popping values off the end of @_ and other things to get at extra values.
So, with the soon-to-be-uploaded version of XML::Writer::Nest, you will write: 
{
my $nest = XML::Writer::Nest->(tag => 'level1');
  { $nest->nest(newlevel => [attr1 => 1, attr2 => 2]);
     ...
  }
}

[download]
instead of 
{
my $nest = XML::Writer::Nest->(tag => 'level1');
  { $nest->nest(newlevel , attr1 => 1, attr2 => 2);
     ...
  }
}

[download]

In reply to API design - if you're expecting a scalar and an array .... by metaperl

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.