view release on metacpan or  search on metacpan

docs/xml/modules/XML/Schema/Attribute/Group.xml  view on Meta::CPAN

    This module implements a class of objects to represent XML Schema
    attribute groups.
  </about>

  <synopsis>
<perl>
use XML::Schema::Attribute::Group;

# create an attribute group
my $group = XML::Schema::Attribute::Group->new({
    attributes => {
	# various ways to define attributes
        foo => 'string',	
        bar => XML::Schema::Attribute->new( {
	    name => 'bar, 
	    type => 'string'
	} ),
        baz => { 
	    name => 'baz', 
	    type => 'string',
	},
        boz => { 
	    # name => 'boz' implied
	    type => 'string',
        },
        wiz => { 
	    type => 'string', 
	    use  => 'required',
        },
        waz => { 
	    type => 'string', 
	    required => 1,	# alternate way to specify use
        },
     },
}) || die XML::Schema::Attribute::Group->error();

# another way (of several) to specify usage
my $group = XML::Schema::Attribute::Group->new({
    attributes  => { ... },
    default_use => 'required',
    optional    => [ qw( foo bar ) ],
}) || die XML::Schema::Attribute::Group->error();

# fetch existing and add new attributes
my foo = $group->attribute('foo');
$group->attribute( XML::Schema::Attribute->new( ... ) );
$group->attribute( name => 'flic', type => 'string', use => REQUIRED );

</perl>
  </synopsis>

  <description>
    <p>
    This module implements an object class for representing XML
    attribute groups within XML Schema.  An attribute group defines a
    collection of attributes and their usage constraints (e.g
    OPTIONAL, REQUIRED or PROHIBITED).  A <module
    class="XML::Schema::Type::Complex">complex type</module> definition
    uses an attribute group to define the acceptable attributes for
    elements of that type.  Attribute groups can also be defined as
    independant entities to represent a relocatable collection of 
    attributes that can be reused in different complex type definitions
    as required.
    </p>
    <p>
    For further information on attribute groups, please consult the
    W3C XML Schema specification.
    </p>
  </description>



  <methods>

    <!-- METHOD: name -->

    <method id="new">
      <p>
        Constructor method called to create a new attribute group.  A
        list of '<perlcode>key =&gt; value</perlcode>' pairs can be
        specified as command line arguments, or alternately, a hash
        reference can be passed which contains these configuration
        values.  The method returns a newly instantiated object on
        success.  On error it returns undef and sets an internal error
        message which can be retrieved by calling <method
        class="XML::Schema::Base">error()</method> as a class method.
<perl>
# list of options
my $group = XML::Schema::Attribute::Group->new( name => 'myGroup' )
     || die XML::Schema::Attribute::Group->error();

# hash ref of options
my $group = XML::Schema::Attribute::Group->new( { name => 'myGroup' } ) 
     || die XML::Schema::Attribute::Group->error();
</perl>
      </p>

      <p>
        The following configuration options may be specifed:
      </p>

      <config>
        <item key="name" value="'myGroup'">
	    The name of the attribute group.
        </item>

        <item key="attributes" value="\%attributes">
	  <p>
	    This item can be used to specify a reference to a hash
            which defines an initial set of attributes for the group.
            Each key in the hash reference denotes the name of an 
	    attribute and each value, the corresponding attribute 
	    definition.  This can be specifed as a reference to an
            <module>XML::Schema::Attribute</module> object, as a 
            simple string denoting the attribute type, e.g. 
	    <perlcode>'integer'</perlcode> or as a reference to 
            a hash array of configuration options from which an
            attribute object will be created.
<perl>
my $group = XML::Schema::Attribute::Group->new({
    attributes => {