![]() |
![]() |
|
|||
|
|||
|
: | 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 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";