Index: trunk/lib/Text/FormBuilder.pm
===================================================================
--- trunk/lib/Text/FormBuilder.pm	(revision 16)
+++ trunk/lib/Text/FormBuilder.pm	(revision 19)
@@ -4,5 +4,7 @@
 use warnings;
 
-our $VERSION = '0.04';
+use vars qw($VERSION);
+
+$VERSION = '0.05';
 
 use Carp;
@@ -20,4 +22,13 @@
 
 sub parse {
+    my ($self, $source) = @_;
+    if (ref $source && ref $source eq 'SCALAR') {
+        $self->parse_text($$source);
+    } else {
+        $self->parse_file($source);
+    }
+}
+
+sub parse_file {
     my ($self, $filename) = @_;
     
@@ -59,5 +70,5 @@
     
     # substitute in custom pattern definitions for field validation
-    if (my %patterns = %{ $self->{form_spec}{patterns} }) {
+    if (my %patterns = %{ $self->{form_spec}{patterns} || {} }) {
         foreach (@{ $self->{form_spec}{fields} }) {
             if ($$_{validate} and exists $patterns{$$_{validate}}) {
@@ -78,5 +89,5 @@
     
     # substitute in list names
-    if (my %lists = %{ $self->{form_spec}{lists} }) {
+    if (my %lists = %{ $self->{form_spec}{lists} || {} }) {
         foreach (@{ $self->{form_spec}{fields} }) {
             next unless $$_{list};
@@ -322,4 +333,7 @@
     # the fields from the input form spec
     my $form = $parser->form;
+    
+    # write a My::Form module to Form.pm
+    $parser->write_module('My::Form');
 
 =head1 DESCRIPTION
@@ -329,5 +343,15 @@
 =head2 parse
 
-    $parser->parse($src_file);
+    # parse a file
+    $parser->parse($filename);
+    
+    # or pass a scalar ref for parse a literal string
+    $parser->parse(\$string);
+
+Parse the file or string. Returns the parser object.
+
+=head2 parse_file
+
+    $parser->parse_file($src_file);
     
     # or as a class method
@@ -338,5 +362,5 @@
     $parser->parse_text($src);
 
-Parse the given C<$src> text. Returns the parse object.
+Parse the given C<$src> text. Returns the parser object.
 
 =head2 build
@@ -348,8 +372,9 @@
 =over
 
-=item form_only
+=item C<form_only>
 
 Only uses the form portion of the template, and omits the surrounding html,
-title, author, and the standard footer.
+title, author, and the standard footer. This does, however, include the
+description as specified with the C<!description> directive.
 
 =back
@@ -398,5 +423,5 @@
 First, you parse the formspec and write the module, which you can do as a one-liner:
 
-    $ perl -MText::FormBuilder -e"Text::FormBuilder->parse('formspec.txt')->write_module('MyForm')"
+    $ perl -MText::FormBuilder -e"Text::FormBuilder->parse('formspec.txt')->write_module('My::Form')"
 
 And then, in your CGI script, use the new module:
@@ -406,8 +431,8 @@
     
     use CGI;
-    use MyForm;
+    use My::Form;
     
     my $q = CGI->new;
-    my $form = MyForm::get_form($q);
+    my $form = My::Form::get_form($q);
     
     # do the standard CGI::FormBuilder stuff
@@ -422,4 +447,7 @@
 will run L<Perl::Tidy> on the generated code before writing the module file.
 
+    # write tidier code
+    $parser->write_module('My::Form', 1);
+
 =head2 dump
 
@@ -429,5 +457,5 @@
 =head1 LANGUAGE
 
-    field_name[size]|descriptive label[hint]:type=default{option1[display string],option2[display string],...}//validate
+    field_name[size]|descriptive label[hint]:type=default{option1[display string],...}//validate
     
     !title ...
@@ -469,4 +497,7 @@
 =item C<!description>
 
+A brief description of the form. Suitable for special instructions on how to
+fill out the form.
+
 =item C<!head>
 
@@ -479,8 +510,88 @@
 =head2 Fields
 
-Form fields are each described on a single line.
+Form fields are each described on a single line. The simplest field is just a
+name:
+
+    color
+
+This yields a form with one text input field of the default size named `color'.
+The label for this field as generated by CGI::FormBuilder would be ``Color''.
+To add a longer or more descriptive label, use:
+
+    color|Favorite color
+
+Field names cannot contain whitespace, but the descriptive label can.
+
+To use a different input type:
+
+    color|Favorite color:select{red,blue,green}
+
+Recognized input types are the same as those used by CGI::FormBuilder:
+
+    text        # the default
+    textarea
+    select
+    radio
+    checkbox
+    static
+
+This example also shows how you can list multiple values for the input types
+that take multiple values (C<select>, C<radio>, and C<checkbox>). Values are
+in a comma-separated list inside curly braces. Whitespace between values is
+irrelevant, although there cannot be any whitespace within a value.
+
+To add more descriptive display text to a vlaue in a list, add a square-bracketed
+``subscript,'' as in:
+
+    ...:select{red[Scarlet],blue[Azure],green[Olive Drab]}
+
+As you can see, spaces I<are> allowed within the display text for a value.
 
 If you have a list of options that is too long to fit comfortably on one line,
-consider using the C<!list> directive.
+consider using the C<!list> directive:
+
+    !list MONTHS {
+        1[January],
+        2[February],
+        3[March],
+        # and so on...
+    }
+    
+    month:select@MONTHS
+
+There is another form of the C<!list> directive: the dynamic list:
+
+    !list RANDOM &{ map { rand } (0..5) }
+
+The code inside the C<&{ ... }> is C<eval>ed by C<build>, and the results
+are stuffed into the list. The C<eval>ed code can either return a simple
+list, as the example does, or the fancier C<( { value1 => 'Description 1'},
+{ value2 => 'Description 2}, ...)> form.
+
+B<NOTE:> This feature of the language may go away unless I find a compelling
+reason for it in the next few versions. What I really wanted was lists that
+were filled in at run-time (e.g. from a database), and that can be done easily
+enough with the CGI::FormBuilder object directly.
+
+You can also supply a default value to the field. To get a default value of
+C<green> for the color field:
+
+    color|Favorite color:select=green{red,blue,green}
+
+To validate a field, include a validation type at the end of the field line:
+
+    email|Email address//EMAIL
+
+Valid validation types include any of the builtin defaults from CGI::FormBuilder,
+or the name of a pattern that you define with the C<!pattern> directive elsewhere
+in your form spec:
+
+    !pattern DAY /^([1-3][0-9])|[1-9]$/
+    
+    last_day//DAY
+
+If you just want a required value, use the builtin validation type C<VALUE>:
+
+    title//VALUE
 
 =head2 Comments
@@ -496,5 +607,5 @@
 Field groups all on one line in the generated form
 
-Tests!
+Better tests!
 
 =head1 SEE ALSO