package HTML::Form::Simple;

use strict;
use warnings;

use XML::Quote;

our $VERSION = '1.00';


sub new {
	my ($class, $default) = @_;
	bless {default => $default}, $class;
}

sub _attr {
	my $self = shift;
	my $expect = shift;
	my $attr = ref $_[-1] eq 'HASH' ? pop : {};
	push @_, undef for @_+1 .. $expect;
	push @_, $attr;
	return @_;
}

sub quote {
	my $self = shift;
	return ${$_[0]} if ref $_[0] eq 'SCALAR';
	return XML::Quote::xml_quote_min($_[0]);
}

sub tag {
	my ($self, $tag, $attr) = @_;

	# strip empty if it shouldn't be
	defined $attr->{$_} and $attr->{$_} eq '' and delete $attr->{$_}
		for qw(id for type class style);

	my $return = '<' . $tag;

	# add boolean attributes
	delete $attr->{$_} and $return .= ' '.$_
		for qw(selected checked disabled readonly);

	# add attributes with (escaped) string values
	$return .= sprintf ' %s="%s"', $_, $self->quote($attr->{$_})
		for sort grep { defined $attr->{$_} } keys %$attr;

	return $return . '>';
}


sub start {
	my ($self, $attr) = @_;

	return $self->tag(form => $attr);
}

sub stop {
	return '</form>';
}


sub submit {
	my $self = shift;
	my ($value, $attr) = $self->_attr(1, @_);

	$attr->{value} = $value if defined $value;
	$attr->{type} = 'submit' unless defined $attr->{type};

	return $self->tag(input => $attr);
}

sub hidden {
	my $self = shift;
	my ($name, $value, $attr) = $self->_attr(2, @_);

	if (ref $name eq 'HASH') {
		my @return = map { $self->hidden($_, $name->{$_}, $attr) } sort keys %$name;
		return wantarray ? @return : join(defined $, ? $, : '', @return);
	}

	if (ref $value eq 'ARRAY') {
		my @return = map { $self->hidden($name, $_, $attr) } @$value;
		return wantarray ? @return : join(defined $, ? $, : '', @return);
	}

	$attr->{name } = $name  if defined $name;
	$attr->{value} = $value if defined $value;
	$attr->{value} = $self->{default}->{$name}
		if not defined $attr->{value} and defined $name and defined $self->{default};
	$attr->{type} = 'hidden' unless defined $attr->{type};

	return $self->tag(input => $attr);
}

sub text {
	my $self = shift;
	my ($name, $value, $attr) = $self->_attr(2, @_);

	$attr->{name } = $name  if defined $name;
	$attr->{value} = $value if defined $value;
	$attr->{value} = $self->{default}->{$name}
		if not defined $attr->{value} and defined $name and defined $self->{default};
	$attr->{id}   = $attr->{name} unless defined $attr->{id};
	$attr->{type} = 'text' unless defined $attr->{type} or defined $attr->{rows};

	# textarea does not have value as tag attribute
	$value = delete $attr->{value} if defined $attr->{rows};

	return defined $attr->{rows} ? sprintf(
		'%s%s</textarea>',
		$self->tag(textarea => $attr),
		$self->quote(defined $value ? $value : '')
	) : $self->tag(input => $attr);
}

sub select {
	my $self = shift;
	my ($name, $rows, $default, $attr) = $self->_attr(3, @_);

	$attr->{name} = $name;
	$attr->{id}   = $attr->{name} unless defined $attr->{id};
	$attr->{type} = 'select' unless defined $attr->{type};

	$default = $attr->{value} unless defined $default;
	delete $attr->{value};  # never a parent attribute
	$default = $self->{default}->{$name}
		if not defined $default and defined $name and defined $self->{default};

	my @options = map { ref $_ ? $_ : {value => $_} } @$rows;

	my @return;

	if ($attr->{type} eq 'select') {
		delete $attr->{type};

		# select option(s) matching the default value
		if (defined $default) {
			for (@options) {
				$_->{selected} = 1 if defined $_->{value} and $_->{value} eq $default;
			}
		}

		@return = (
			$self->tag(select => $attr),
			(map { $self->tag(option => $_) } @options),
			'</select>',
		);
	}
	else {
		# set fallback option id from parent id and value
		if (defined $attr->{id} and $attr->{id} ne '') {
			defined $_->{id}
				or defined $_->{value} and $_->{id} = $attr->{id}.'_'.$_->{value}
					for @options;
		}

		# put parent label attribute on options
		if (defined $attr->{label}) {
			defined $_->{value} and not defined $_->{label}
				and $_->{label} = $attr->{label}->{$_->{value}}
					for @options;
			delete $attr->{label};
		}

		# check any option matching the default value
		if (defined $default) {
			for (@options) {
				$_->{checked} = 1 if defined $_->{value} and $_->{value} eq $default;
			}
		}

		$_ = {%$attr, %$_} for @options;
		@return = map {
			my $label = delete $_->{label};
			defined $label && $label ne ''
				? '<label>'.$self->tag(input => $_)." $label</label>"
				:           $self->tag(input => $_)
		} @options;
	}

	return wantarray ? @return : join(defined $, ? $, : '', @return);
}

sub radio {
	my $self = shift;
	my ($name, $rows, $label, $default, $attr) = $self->_attr(4, @_);

	# normalize rows array
	if (not defined $rows) {
		if (defined $label) {
			# fill up values with numbers to match labels
			$rows = ref $label eq 'ARRAY' ? [1 .. $#$label+1] : [1];
		}
		else {
			$rows = [{}];
		}
	}
	elsif (ref $rows ne 'ARRAY') {
		$rows = [$rows];
	}

	# add labels
	if (defined $label) {
		# convert options to hash refs so we can add label attributes
		$rows = [ map { ref $_ eq 'HASH' ? {%$_} : {value => $_} } @$rows ];

		if (ref $label eq 'ARRAY') {
			$rows->[$_]->{label} = $label->[$_] for 0 .. $#$rows;
		} else {
			$_->{label} = $label for @$rows;
		}
	}

	$self->select($name, $rows, $default, {%$attr, type => 'radio'});
}

sub check {
	my $self = shift;
	my ($name, $label, $checked, $attr) = $self->_attr(3, @_);

	# create option rows array from label argument
	my $rows = defined $label ? ref $label eq 'ARRAY' ? [@$label] : [$label] : [{}];
	# convert options to hash refs sooner rather than later
	$_ = ref $_ eq 'HASH' ? {%$_} : {label => $_} for @$rows;

	# parse checked argument
	if (defined $checked) {
		if (ref $checked eq 'ARRAY') {
			# each checked row corresponding to an option
			$rows->[$_]->{checked} = $checked->[$_] for 0 .. $#$rows;
			# add superfluous rows as new options
			push @$rows, map { {checked => $_} } @$checked[@$rows .. $#$checked];
		}
		else {
			# a single value for all options
			$_->{checked} = $checked for @$rows;
		}
	}

	# set default option value (argument number)
	exists $rows->[$_]->{value} or $rows->[$_]->{value} = $_ + 1 for 0 .. $#$rows;

	# set option id without added value if rows were not given as array
	$rows->[0]->{id} = $attr->{id} || $rows->[0]->{name} || $attr->{name} || $name #XXX: //
		if ref $label ne 'ARRAY' and defined $rows->[0] and not defined $rows->[0]->{id};

	$self->select($name, $rows, {%$attr, type => 'checkbox'});
}

sub row {
	my $self = shift;
	my ($name, $contents, $attr) = $self->_attr(2, @_);

	$contents = defined $contents && ref $contents ne 'HASH'
		? $self->quote($contents) : $self->text($name, $contents);
	my $label = defined $attr->{label}
		? $self->quote(delete $attr->{label})
		: defined $name ? $self->quote($name) : '';

	return $self->tag(label => {for => $name, %$attr})
		. $label
		. '</label>'
		. (defined $, ? $, : ' ')
		. $contents
		;
}

1;

__END__

=head1 NAME

HTML::Form::Simple - Generate HTML form elements

=head1 SYNOPSIS

	my $input = HTML::Form::Simple->new;
	say $input->start; # <form>
	printf "<label>%s: %s</label>\n", @$_ for (
		[ 'Your Name' => $input->text(
			user => 'Mr. Default'
		) ],
		[ Message => $input->text(
			msg => 'Textarea default', {rows => 4, style => 'background:red'}
		) ],
		[ Gender => join ' or ', $input->radio(
			sex => [qw(m f)], [qw(Male Female)]
		) ],
		[ Colour => scalar $input->select(
			favcolour => [qw(Blue Green Red)], 'Green'
		) ],
		[ Options => $input->check(
			spam => 'Receive weekly newsletter'
		) ],
	);
	say $input->stop; # </form>

=head1 DESCRIPTION

Set up a form object with new().  The HTML for the opening and closing
C<< <form> >> tags are returned by the start() and stop() methods.

The L<hidden>, L<text>, L<select>, L<radio>, and L<check> methods all
correspond to various input types.  The first argument is always the mandatory
name, and a hash ref as the last argument can optionally be provided for
additional attributes/options.  Everything is properly escaped.

=over

=item C<hidden>

Returns the HTML for a simple C<< <input type="hidden"> >> with specified name
and value (both are required by HTML specs).

	$input->hidden('name', 'value');

As with all methods, a final hash ref can be given to add further attributes.
While rarely needed in this case, it can also be used as an override or
alternative to value and name:

	$input->hidden({name => 'name', value => 'value'})

=item C<text>

The common C<< <input type="text"> >>.

	$input->text('name', 'default');

If the I<rows> option is set, substitutes a similarly set up C<< <textarea> >>:

	$input->text('name', 'default', {rows => 4});

=item C<select>

	$input->select('name', ['option'], 'default');

Provides C<< <select><option> >> dropdown by default, but can also output
multiple C<< <input> >> tags if a I<type> is provided:

	$input->select('name', ['1'], {type => 'checkbox'});

In scalar context, options are joined together by C<$,> (C<$OUTPUT_FIELD_SEPARATOR>).
Otherwise a list of tags is returned.

Each option can be given as either a simple string containing its I<value>,
or a hash ref with custom attributes.
When there's no parent tag (only C<< <input> >>s), a fourth parameter can
provide common options which will be inherited by each element.  Otherwise,
options will apply to either the C<< <select> >> or an C<< <option> >>.

The default value (either as a third scalar parameter, or with the general
I<value> option) will be matched to the value of each option, and if equal,
its I<selected> or I<checked> attribute will be set as appropriate.

=item C<radio>

In fact just a shorthand to L<select> with a preset type of I<radio>, but takes
an additional third argument to easily set the label for each option:

	$input->radio('name', ['option'], ['option label'], 'default');

This would be the same as saying:

	$input->radio(
		'name',
		[ {label => 'option label', value => 'option'} ],
		{value => 'default'}
	);

=item C<check>

Also a L<select> shorthand, but with a I<checkbox> type.
Instead of values, the second argument specifies option I<label>s.
The values by default are set to an auto-incrementing number starting with 1.

Furthermore, the I<checked> status for each option can be specified by a third
argument.  Either a single boolean value defining all rows, or an array ref
with the value for each row in order.

	$input->check('name', ['label', 'second option'], [0, 1]);

Or more descriptive but identical:

	$input->check('name', [
		{label => 'label',         value => 1, checked => 0},
		{label => 'second option', value => 2, checked => 1},
	]);

=back

=head1 TODO

=over

=item C<default()> method

	$input->hidden(foo => $input->default('foo'));
	$hash_ref = $input->default;
	$input->default('foo') = 'new value';
	undef $input->default;  # clear all
		# XXX: does this equal $input->default=undef;?
	$input->default = {amend => 'stuff'};

=item documentation

Actual descriptions instead of just a synopsis.

=item C<quote> override

Allow custom value quotation function.
Makes L<XML::Quote|XML::Quote> dependency optional.

=item single checkbox id

Do not add value to single check() by default.

=back

=head1 AUTHOR

Mischa POSLAWSKY <perl@shiar.org>

=head1 LICENSE

This module is free software; you can redistribute it and/or modify it
under the same L<terms|perlartistic> as Perl itself.

