TWiki/TWikiAttrsDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Attrs="></a> Package =TWiki::Attrs
   2
   3 Class of attribute sets, designed for parsing and storing attribute values from a TWiki tag e.g. `%TAG{"joe" fred="bad" joe="mad"}%`
   4
   5 An attribute set is a hash containing an entry for each parameter. The default parameter (unnamed quoted string) is named `_DEFAULT` in the hash.
   6
   7 Attributes declared later in the string will override those of the same name defined earlier. The one exception to this is the \_DEFAULT key, where the _first_ instance is always taken.
   8
   9 As well as the default TWiki syntax (parameter values double-quoted) this class also parses single-quoted values, unquoted spaceless values, spaces around the =, and commas as well as spaces separating values. The extended syntax has to be enabled by passing the `$friendly` parameter to `new`.
  10
  11 <div>
  12   <ul>
  13     <li><a href="#Package =TWiki::Attrs="> Package TWiki::Attrs</a><ul>
  14         <li><a href="#ClassMethod <strong>new</strong> ($string,$frie"> ClassMethod new <tt>($string,$friendly)=&gt;\%attrsObjectRef</tt></a></li>
  15         <li><a href="#ObjectMethod <strong>isEmpty</strong> () -> boo"> ObjectMethod isEmpty <tt>() -&gt; boolean</tt></a></li>
  16         <li><a href="#ObjectMethod <strong>remove</strong> ($key) ->"> ObjectMethod remove <tt>($key) -&gt; $value</tt></a></li>
  17         <li><a href="#ObjectMethod <strong>stringify</strong> () -> $"> ObjectMethod stringify <tt>() -&gt; $string</tt></a></li>
  18       </ul>
  19     </li>
  20   </ul>
  21 </div>
  22
  23 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($string,$frie"></a> [[ClassMethod]] **new** `($string,$friendly)=>\%attrsObjectRef`
  24
  25 - `$string` - String containing attribute specification
  26 - `$friendly` - if true, the parse will be according to the extended syntax pioneered by the original Contrib::Attrs. Otherwise it will be strict as per traditional TWiki syntax.
  27
  28 Parse a standard attribute string containing name=value pairs and create a new attributes object. The value may be a word or a quoted string. If there is an error during parsing, the parse will complete but $attrs-&gt;\{\_ERROR\} will be set in the new object. $attrs-&gt;\{\_RAW\} will always contain the full unprocessed $string.
  29
  30 Extended syntax example:
  31
  32     my $attrs = new TWiki::Attrs('the="time \\"has come", "the walrus" said to=speak of=\'many \\'things\', 1);
  33
  34 In this example:
  35
  36 - `the` will be `time "has come`
  37 - `__default__` will be `the walrus`
  38 - `said` will be `on`
  39 - `to` will be `speak`
  40 - `of` will be `many 'things`
  41
  42 Only " and ' are escaped.
  43
  44 Traditional syntax is as old TWiki, except that the whole string is parsed (the old parser would only recognise default values in position 1, nowhere else)
  45
  46 ## <a name="ObjectMethod &lt;strong&gt;isEmpty&lt;/strong&gt; () - bool"></a> [[ObjectMethod]] **isEmpty** `() -> boolean`
  47
  48 Return false if attribute set is not empty.
  49
  50 ## <a name="ObjectMethod &lt;strong&gt;remove&lt;/strong&gt; ($key) - $"></a> [[ObjectMethod]] **remove** `($key) -> $value`
  51
  52 - `$key` - Attribute to remove
  53
  54 Remove an attr value from the map, return old value. After a call to `remove` the attribute is no longer defined.
  55
  56 ## <a name="ObjectMethod &lt;strong&gt;stringify&lt;/strong&gt; () - $s"></a> [[ObjectMethod]] **stringify** `() -> $string`
  57
  58 Generate a printed form for the map, using strict attribute syntax, with only the single-quote extension syntax observed (no \{\} brackets, though).