data/TWiki/TWikiAttrsDotPm.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
     1 head	1.3;
     2 access;
     3 symbols;
     4 locks; strict;
     5 comment	@# @;
     6 
     7 
     8 1.3
     9 date	2008.01.22.03.21.26;	author TWikiContributor;	state Exp;
    10 branches;
    11 next	1.2;
    12 
    13 1.2
    14 date	2007.01.16.04.12.00;	author TWikiContributor;	state Exp;
    15 branches;
    16 next	1.1;
    17 
    18 1.1
    19 date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    20 branches;
    21 next	;
    22 
    23 
    24 desc
    25 @new-topic
    26 @
    27 
    28 
    29 1.3
    30 log
    31 @buildrelease
    32 @
    33 text
    34 @---+ Package =TWiki::Attrs=
    35 
    36 Class of attribute sets, designed for parsing and storing attribute values
    37 from a TWiki tag e.g. =%<nop>TAG{"joe" fred="bad" joe="mad"}%=
    38 
    39 An attribute set is a hash containing an entry for each parameter. The
    40 default parameter (unnamed quoted string) is named <code>_<nop>DEFAULT</code> in the hash.
    41 
    42 Attributes declared later in the string will override those of the same
    43 name defined earlier. The one exception to this is the _DEFAULT key, where
    44 the _first_ instance is always taken.
    45 
    46 As well as the default TWiki syntax (parameter values double-quoted)
    47 this class also parses single-quoted values, unquoted spaceless
    48 values, spaces around the =, and commas as well as spaces separating values.
    49 The extended syntax has to be enabled by passing the =$friendly= parameter
    50 to =new=.
    51 
    52 
    53 %TOC%
    54 
    55 ---++ ClassMethod *new* <tt>($string,$friendly)=>\%attrsObjectRef</tt>
    56 
    57    * =$string= - String containing attribute specification
    58    * =$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.
    59 
    60 Parse a standard attribute string containing name=value pairs and create a new
    61 attributes object. The value may be a word or a quoted string. If there is an
    62 error during parsing, the parse will complete but $attrs->{_ERROR} will be
    63 set in the new object. $attrs->{_RAW} will always contain the full unprocessed
    64 $string.
    65 
    66 Extended syntax example:
    67 <verbatim>
    68 my $attrs = new TWiki::Attrs('the="time \\"has come", "the walrus" said to=speak of=\'many \\'things\', 1);
    69 </verbatim>
    70 In this example:
    71    * =the= will be =time "has come=
    72    * <code>_<nop>_<nop>default__</code> will be =the walrus=
    73    * =said= will be =on=
    74    * =to= will be =speak=
    75    * =of= will be =many 'things=
    76 
    77 Only " and ' are escaped.
    78 
    79 Traditional syntax is as old TWiki, except that the whole string is parsed
    80 (the old parser would only recognise default values in position 1, nowhere
    81 else)
    82 
    83 
    84 
    85 ---++ ObjectMethod *isEmpty* <tt>() -> boolean</tt>
    86 
    87 Return false if attribute set is not empty.
    88 
    89 
    90 
    91 ---++ ObjectMethod *remove* <tt>($key) -> $value</tt>
    92 
    93    * =$key= - Attribute to remove
    94 Remove an attr value from the map, return old value. After a call to
    95 =remove= the attribute is no longer defined.
    96 
    97 
    98 
    99 ---++ ObjectMethod *stringify* <tt>() -> $string</tt>
   100 
   101 Generate a printed form for the map, using strict
   102 attribute syntax, with only the single-quote extension
   103 syntax observed (no {} brackets, though).
   104 
   105 
   106 @
   107 
   108 
   109 1.2
   110 log
   111 @buildrelease
   112 @
   113 text
   114 @d4 1
   115 a4 1
   116 from a TWiki tag e.g. =%TAG{fred='bad' "sad" joe="mad"}%=
   117 d6 2
   118 a7 2
   119 An attribute set is a map containing an entry for each parameter. The
   120 default parameter (unnamed quoted string) is named <code>_<nop>DEFAULT</code> in the map.
   121 d11 1
   122 a11 1
   123 the _first_ instance of a setting is always taken.
   124 d13 4
   125 a16 5
   126 As well as standard TWiki syntax (parameter values double-quoted)
   127 it also parses single-quoted values, unquoted spaceless
   128 values, spaces around the =, and commas as well as spaces separating values,
   129 though none of these alternatives is advertised in documentation and
   130 the extended syntax can be turned off by passing the 'strict' parameter
   131 a18 3
   132 This class replaces the old TWiki::extractNameValuePair and
   133 TWiki::extractParameters.
   134 
   135 d60 1
   136 a60 1
   137 | $key | Attribute to remove |
   138 d68 1
   139 a68 1
   140 Generate a printed form for the map, using standard
   141 a72 23
   142 
   143 ---++ StaticMethod *extractValue* <tt>() -> $string</tt>
   144 
   145 Legacy support, formerly known as extractNameValuePair. This
   146 static method uses context information to determine how a value
   147 string is to be parsed. For example, if you have an attribute string
   148 like this:
   149 
   150 "abc def="ghi" jkl" def="qqq"
   151 
   152 then call extractValue( "def" ), it will return "ghi".
   153 
   154 
   155 
   156 ---++ ObjectMethod *get* <tt>($key) -> $value</tt>
   157 
   158 | $key | Attribute to get |
   159 Get an attr value from the map.
   160 
   161 Synonymous with $attrs->{$key}. Retained mainly for compatibility with
   162 the old AttrsContrib.
   163 
   164 
   165 @
   166 
   167 
   168 1.1
   169 log
   170 @buildrelease
   171 @
   172 text
   173 @d2 1
   174 d27 1
   175 d57 1
   176 d63 1
   177 d71 1
   178 d79 1
   179 d91 1
   180 a92 1
   181 ---++ ObjectMethod *get* <tt>($key) -> $value</tt>
   182 @