
=head1 NAME

HTML::DOM::Collection::Options - A subclass of HTML::DOM::Collection for 'option' elements

=head1 SYNOPSIS

  use HTML::DOM;
  $doc = HTML::DOM->new;
  $doc->write('
      <form name=theform>
        <select name=choice>
          <option>
          <option>
        </select>
      </form>
  ');
  $doc->close;
  
  $options = $doc->forms->{theform}{choice}->options;
  # returns an HTML::DOM::Collection::Options object
  
  $options->[0]; # first option
  $options->item(0); # same

  $options->

  $elements->{r}; # an array of buttons named 'r'
  $elements->namedItem('r'); # same
  () = $elements->namedItem('r'); # list, not array
  
  $elements->length; # same as $#$elements

=head1 DESCRIPTION

This inherits from L<HTML::DOM::Collection> and adds a few extra methods
for compatibility with L<WWW::Mechanize>. This is used to represent a
'select' element's list of options.

=head1 CONSTRUCTOR

Normally you would simply call L<HTML::DOM::Element::Select>'s C<options>
method
(as in the L</SYNOPSIS>). But if you wall to call the constructor anyway, 
here is
the syntax:

  $elements = HTML::DOM::Collection::Options->new($nodelist)

$nodelist should be a node list (L<HTML::DOM::NodeList>) object.

=head1 METHODS

=over 4

=item $options->length

Returns the number of items in the collection.

=item $options->item($index)

Returns item number C<$index>, numbered from 0. Note that you call also use
C<< $elements->[$index] >> for short.

=item $options->namedItem($name)

Returns the item named C<$name>. You can also write C<< $collection->{$name} >>.

=back

These last few are provided for L<WWW::Mechanize> compatibility.

=over 4

=item $options->type

Returns the string 'option'.

=item $options->name

Returns the name of the 'select' element.

=item $options->possible_values

Returns the a list of the options' values. Provided for L<WWW::Mechanize> 
compatibility.

=item $options->value

=item $options->value('new_value');

Selects the option with the value given and returns the old value, or
simply returns the value if there is no argument.

=item $options->disabled

Returns true if all the options are disabled, false otherwise.

=item $options->form_name_value;

Returns a list consisting of (0) the name of the 'select' element and (1)
the value of the selected option.

=back

=head1 BUGS

The C<name> and C<form_name_value> methods currently die if there are no 
options.

=head1 SEE ALSO

L<HTML::DOM>

L<HTML::DOM::Collection>

L<HTML::DOM::Element::Select>

L<HTML::DOM::Element::Form>

The source of HTML/DOM/Element/Form.pm, where this is implemented.
