|  |  | 
|  | |||
|  | |||
|  | : | new(), name(), namespace(), scope(), attribute(), attributes(), default_use(), use(), required(), optional(), prohibited(), group(), groups() | 
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 );
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 complex type 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.
For further information on attribute groups, please consult the W3C XML Schema specification.
        Constructor method called to create a new attribute group.  A
        list of 'key => value
' 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 error() as a class method.
# 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();
The following configuration options may be specifed:
| Name | Typical Values | Description | 
| name | 'myGroup' | The name of the attribute group. | 
| attributes | \%attributes | 
	    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
            XML::Schema::Attribute object, as a 
            simple string denoting the attribute type, e.g. 
	     
 
            In additional to all the arguments accepted by the
            XML::Schema::Attribute  
 
	    Alternately, the hash may contains one of the keys
	    ' 
 | 
| use | \%usage | 
	    The ' 
 The XML::Schema::Constants module defines a set of constants to represent these values. 
 
            Note that while the 
            above constants are represented in UPPER CASE,  e.g.
             | 
| default_use | $use | 
	    The ' 
 | 
| required | \@names | 
	    This option provides an alternate way of specifying that
	    certain attributes are  
 | 
| optional | \@names | 
	    Like  
 | 
| prohibited | \@names | 
	    To complete the trilogy, this option allows  
 | 
| group | $group$group_name\%group_config | This configuration item can be used to specify a sub-group that the attribute group should adopt. All attributes and any wildcard defined in the sub-group will then become part of the validation set for the current attribute group. The value can be specified as a reference to an existing XML::Schema::Attribute::Group object, as a hash reference of configuration options from which such an object can be created, or as a name by which the attribute group can be fetched from the current scope. | 
| groups | [ $group, $group_name, \%group_config, ... ] | This option is like groupdescribed above but 
	      accepts a reference to a list of multiple groups, each item of which 
	      should be one of the acceptable parameters as forgroup. | 
| scope | $scope | This configuration item can be used to bind the attribute group to a particular lexical scope. See the corresponding entry in the XML::Schema::Attribute documentation for further details. | 
| namespace | 'http://tt2.org/XML/xyz.xml' | The optional XML namespace for the attribute group. | 
| annotation | '...interesting note...' | An optional annotation for the attribute group. This is not yet fully supported. | 
name()
      Returns the attribute group name.
my $name = $group->name();
namespace(  )
namespace( $new_namespace )
      
      
      Returns the namespace of the attribute group as optionally
      specified by the namespace configuration item.
      Can also be called with a single argument to set a new namespace
      value.
my $ns = $group->namespace(); $group->namespace('http://tt2.org/XML/Example.xml');
scope(  )
scope( $new_scope )
      
      
      Returns the current scope as specified in the
      scope configuation item.  Can also be called
      with a single argument to define a new scope for the attribute
      group.  This should be a reference to an object which inherits
      from the XML::Schema::Scope class.
my $scope = $group->scope(); $group->scope($new_scope);
attribute( $name )
attribute( $attribute )
attribute( name => $name, type => $type, ... )
      
      
      
      
        This method provides a way to retrieve existing attribute
        definitions and also provide new ones.  When called with a
        single non-reference argument, $name
, the
        method returns the attribute
        object indicated by that name.  If the attribute is not defined
        then undef
 is returned and an appropriate
        error is set.
my $attr = $group->attribute('foo') || die $group->error();
When called with a single argument, $attribute, which is a reference to an XML::Schema::Attribute object, then the attribute is added to the group.
$group->attribute( XML::Schema::Attribute->new( ... ) ) || die $group->error();
Finally, the method can be called with a list of configuration values or a reference to a hash containing those values from which a new attribute object can be instantiated and added to the group. The method returns a reference to the new object created.
my $flic = $group->attribute( name => 'flic', type => 'string' ) || die $group->error(); my $flac = $group->attribute( { name => 'flac', type => 'string', use => 'required' } ) || die $group->error();
attributes()
	This method returns a reference to the hash array containing all 
	attribute definitions within the group.  Modifying entries in this 
        hash will have direct effect upon the group.  Use carefully.
    
default_use(  )
default_use( $new_use )
      
      
      Returns the current default usage value for attributes when 
      called without any arguments.  This will be one of the strings
      'optional
',
      'required
' or
      'prohibited
'.  Can also be called with an
      argument, one of those same strings, to set the new default usage
      policy.   Note that this only affects new attributes created via
      the attribute() method after the call and does
      not affect any attributes already defined within the group.
my $use = $group->default_use(); $group->default_use('required');
use( $name )
use( $name, $use )
      
      
      When called with a single argument, $name
, this
      method returns the usage string (as above) for the named attribute.
      Can also be called with a second argument to set a new usage for the
      attribute.
my $foo_use = $group->use('foo'); $group->use( foo => 'required' );
required(  )
required( $name )
required( $name, $use )
      
      
      
      When called without any arguments, this method retursn a
      reference to a list containing the names of all
      REQUIRED
 attributes in the group.  When
      called with a single argument, $name
, it
      returns true (1) if the named attribute is
      REQUIRED
 or false (0) if not.  It can also
      be called with a third argument which is a flag used to set 
      the attribute's usage to REQUIRED
 when
      true or OPTIONAL
 otherwise.
my $req_hash = $group->required(); my $foo_req = $group->required('foo'); $group->required( foo => 1 );
optional(  )
optional( $name )
optional( $name, $use )
      
      
      
      As per required() above, this method provides
      a way to fetch and set OPTIONAL
 attribute
      usage.
my $opt_hash = $group->optional(); my $foo_opt = $group->optional('foo'); $group->optional( foo => 1 );
prohibited(  )
prohibited( $name )
prohibited( $name, $use )
      
      
      
      As per required() and
      optional() above, this method provides a way to
      fetch and set PROHIBITED
 attribute usage.
my $not_hash = $group->prohibited(); my $foo_not = $group->prohibited('foo'); $group->prohibited( foo => 1 );
group( $name )
group( $group )
group( name => $name, attributes => { ... }, ... )
      
      
      
      
        This method provides a way to define a new attribute group
        that should be added as a sub-group of the current group.  All
        attributes, wildcards and further sub-groups of the new group
        will become valid for the current group and all its validation
        rules will apply.  For example, if a sub-group defines a
        required attribute then the current attribute
	group will then also require it.
      
The new group can either be specified as a reference to an existing XML::Schema::Attribute::Group object, a reference to a hash array of configuration parameters that can be used to instantiate an object of that class, or a simple string indicating a name by which the attribute group can be accessed from the enclosing scope.
$group->group( XML::Schema::Attribute::Group->new(...) ) || die $group->error(); $group->group( { name => 'my_new_group', attributes => { ... }, } ) || die $group->error(); $group->group('my_other_group') || die $group->error();
	Note the important distinction between this method and the
	attribute_group()
	method inherited from XML::Schema::Scope.  The
	latter creates (if necessary) an attribute group object and
	defines it by name in the internal scope lookup table.
	However, it does not bind it to the current attribute group to
	contribute to the validation of instance document attributes.
	The group() method delegates to attribute_group() to
	create and register the new group and then then adds the name of
	the group to the internal table which binds it into the current 
        group.
      
groups()
	This method returns a reference to a list of the names of
        other attribute groups that are bound to the current group to
        contribute to validation.  The actual group references
        themselves can be fetch via the attribute_group() method.
my $groups = $group->groups(); print $group->name, " has sub-groups: ", join(', ', @$groups), "\n";