Common attributes parser code module, for use by Plugins authors.

---+ Summary of Contents
Provides a simple and consistent interface for creation and management of lists of standard TWiki-syntax attribute value lists, as used in tags.

---+ Detailed Documentation
---++ Package TWiki::Contrib::Attrs
Class of attribute sets, designed for parsing and storing attribute values
from a TWiki tag e.g. =%TAG{fred="bad" "sad" joe="mad"}%=

An attribute set is a map containing an entry for each parameter. The
default parameter (unnamed quoted string) is named <code>__<nop>default__</code> in the map.
Attributes declared later in the string will override those of the same
name defined earlier. Escaping quotes is _not_ supported.

The parser is forgiving; it will handle standard TWiki syntax (parameter
values double-quoted) but also single-quoted values, unquoted spaceless
values, spaces around the =, and commas as well as spaces separating values.

---+++ new ($string) => Attrs object ref
| $string | String containing attribute specification |
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 $this->{__error__} will be
set in the new object.

Example:
<verbatim>
use TWiki::Contrib::Attrs;
my $attrs = new TWiki::Contrib::Attrs('the="time has come", "the walrus" said to=speak of='many things');
</verbatim>
In this example:
   * =the= will be =time has come=
   * <code>_<nop>_<nop>default__</code> will be =the walrus=
   * =said= will be =on=
   * =to= will be =speak=
   * =of= will be =many things=

---+++ get( $key) => value
| $key | Attribute name |
Get an attr value; return undef if not set

---+++ isEmpty() => boolean
Return false if attribute set is not empty.

---+++ remove($key) => value
| $key | Attribute to remove |
Remove an attr value from the map, return old value. After a call to
=remove= the attribute is no longer defined.

---+++ toString() => string
Generate a printed form for the map, using standard
attribute syntax, with only the single-quote extension
syntax observed (no {} brackets, though).



---++ Settings
	* Name of the perl package
		* Set STUB = TWiki::Contrib::Attrs

---++ Installation Instructions

	* Download the ZIP file from the Plugin web (see below)
	* Unzip ==%TOPIC%.zip== in your twiki installation directory. Content: 
	| *File:* | *Description:* |
	| ==data/TWiki/AttrsContrib.txt== |  |
	| ==lib/TWiki/Contrib/Attrs.pm== |  |
	| ==lib/TWiki/Contrib/AttrsContrib/test.zip== |  |
	| ==lib/TWiki/Contrib/AttrsContrib/build.pl== |  |


---++ Plugin Info

|  Author: | TWiki:Main/CrawfordCurrie http://www.c-dot.co.uk |
|  Copyright &copy;: | 2001, Motorola Corp, All Rights Reserved |
|  License: | GPL |
|  Dependencies: | None |
|  Change History: | |
|  14/08/04 | Separated out from SharedCode module |
|  Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences

-- TWiki:Main/CrawfordCurrie - 12:53:50 16 August 2004

<!-- Do _not_ attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the Dev topic instead. -->
