Modules Index

XML Schema Home

# XML::Schema::Attribute::Group

This module implements a class of objects to represent XML Schema attribute groups.

## Table of Contents

Synopsis |  |  |
Description |  |  |
Methods | : | new(), name(), namespace(), scope(), attribute(), attributes(), default_use(), use(), required(), optional(), prohibited(), group(), groups() |

## Synopsis

    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 );

## Description

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.

## Methods

- new()

  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. `'integer'` or as a reference to a hash array of configuration options from which an attribute object will be created.

      my $group = XML::Schema::Attribute::Group->new({
          attributes => {
              foo => 'string',
              bar => XML::Schema::Attribute->new( {
      	    name => 'bar,
      	    type => 'string'
      	} ),
              baz => {
      	    name => 'baz',
      	    type => 'string',
      	},
              boz => {
      	    # name => 'boz' implied
      	    type => 'string',
              },
           },
      }) || die XML::Schema::Attribute::Group->error();
  In additional to all the arguments accepted by the XML::Schema::Attribute `new()` method, the hash array may also contain a '`use` ' key set to a value of `'optional'` , `'required'` or `'prohibited'` to indicate the designated usage constraints on the attribute.

      my $group = XML::Schema::Attribute::Group->new({
          attributes => {
              flic => {
      	    type => 'string',
      	    use  => 'optional',
      	},
              flac => {
      	    type => 'integer',
      	    use  => 'required',
              },
           },
      }) || die XML::Schema::Attribute::Group->error();
  Alternately, the hash may contains one of the keys '`optional` ', '`required` ' or '`prohibited` ' with a true corresponding value to achieve the same effect.

      my $group = XML::Schema::Attribute::Group->new({
          attributes => {
              flic => {
      	    type => 'string',
      	    optional => 1,
      	},
              flac => {
      	    type => 'integer',
      	    required => 1,
              },
           },
      }) || die XML::Schema::Attribute::Group->error();
  `use` | `\%usage` | The '`use` ' item can be used to specify a reference to a hash array which maps attribute names to their usage constraints, for those that don't explicitly specify their own '`use` ' option in the `attributes` hash as described above.

      my $group = XML::Schema::Attribute::Group->new({
          attributes => { ... },
          use => {
      	foo => 'required',
      	bar => 'optional',
          },
      }) || die XML::Schema::Attribute::Group->error();
  The XML::Schema::Constants module defines a set of constants to represent these values.

      use XML::Schema::Constants qw( :attribs );

      my $group = XML::Schema::Attribute::Group->new({
          attributes => { ... },
          use => {
      	foo => REQUIRED,
      	bar => OPTIONAL,
          },
      }) || die XML::Schema::Attribute::Group->error();
  Note that while the above constants are represented in UPPER CASE, e.g. `REQUIRED` , the actual values that they represent, and the ones that you should use if you don't opt for the constants, are all in lower case, e.g. `'required'` .
  `default_use` | `$use` | The '`default_use` ' item can be used to specify the default usage for attributes that don't define it in any other way. The default value for this is '`optional` '.

      my $group = XML::Schema::Attribute::Group->new({
          attributes  => { ... },
          default_use => 'required',
      }) || die XML::Schema::Attribute::Group->error();
  `required` | `\@names` | This option provides an alternate way of specifying that certain attributes are `REQUIRED` . It should contain a reference to a list which names all required attributes.

      my $group = XML::Schema::Attribute::Group->new({
          attributes  => { ... },
          required    => [ qw( foo bar ) ],
      }) || die XML::Schema::Attribute::Group->error();
  `optional` | `\@names` | Like `required` above, option provides an alternate way of specifying `OPTIONAL` attributes.

      my $group = XML::Schema::Attribute::Group->new({
          attributes  => { ... },
          default_use => 'required',
          optional    => [ qw( baz boz ) ],
      }) || die XML::Schema::Attribute::Group->error();
  `prohibited` | `\@names` | To complete the trilogy, this option allows `PROHIBITED` attributes to be declared.

      my $group = XML::Schema::Attribute::Group->new({
          attributes  => { ... },
          prohibited  => [ qw( baz boz ) ],
      }) || die XML::Schema::Attribute::Group->error();
  `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 `group` described above but accepts a reference to a list of multiple groups, each item of which should be one of the acceptable parameters as for `group`.
  `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";

Perl XML::Schema Documentation