package Bigtop::Backend::Control;
use strict; use warnings;

use Bigtop::Keywords;

#-----------------------------------------------------------------
#   Register keywords in the grammar
#-----------------------------------------------------------------

my %controller_keywords;

BEGIN {
    my @controller_keywords = qw(
            controls_table
            gen_uses
            stub_uses
            uses
            text_description
    );

    @controller_keywords{ @controller_keywords } = @controller_keywords;
    
    Bigtop::Parser->add_valid_keywords(
        Bigtop::Keywords->get_docs_for(
            'controller',
            qw(
                controls_table
                gen_uses
                stub_uses
                uses
                text_description
                location
                rel_location
                skip_test
                soap_name
                namespace_base
            )
        )
    );

    Bigtop::Parser->add_valid_keywords(
        Bigtop::Keywords->get_docs_for(
            'app',
            qw(
                authors
                contact_us
                email
                copyright_holder
                license_text
                uses
                location
            )
        )
    );
    
}

sub is_controller_keyword {
    shift;
    my $candidate = shift;

    return $controller_keywords{ $candidate };
}

1;

=head1 NAME

Bigtop::Backend::Control - defines legal keywords in control blocks

=head1 SYNOPSIS

If you are making a control generating backend:

    use Bigtop::Backend::Control;

This specifies the valid keywords for the controller.

If you need additional keywords which are generally useful, add them
here (and send in a patch).  If you need backend specific keywords, register
them within your backend module.

=head1 DESCRIPTION

If you are using a Bigtop backend which generates controllers, you should read
this document to find out what the valid keywords inside controller blocks
are and what affect they have.

If you are writing a Bigtop backend which generates controllers, you should
use this module.  That will register the standard controller keywords with
the Bigtop parser.

=head1 BASIC STRUCTURE

A controller block looks like this:

    controller name { }

Inside the braces, you can include simple statements or method blocks.
Each method block looks like this:

    method name is type { }

The type must be supported by your backend.  Look in its pod for
SUPPORTED TYPES.

=head1 KEYWORDS in app blocks

This module registers these keywords in app blocks:

=over 4

=item authors

These are the authors which Control backends will put in the pod
stub for each generated module.  Unless you use the copyright_holder
statement, the first author will also be used as the copyright holder.

Entries in this list may be either simple names or name => email pairs.

=item contact_us

Text to include in the CONTACT US section of the base module's POD.

=item copyright_holder

This string will come at the end of the phrase Copyright...
in the pod.  By default, it will be the first person in the authors list.

=item email

Deprecated synonymn for contact_us.

This will be presented by the Control backend as the author's email
in the AUTHOR section of the pod block at the bottom of each module.

=item license_text

The exact text of the paragraph that comes directly after the copyright
statement in the all files that have that.  Controllers should pick
a default that h2xs would have generated for Perl version 5.8 or later.

Example:

    copyright_holder `Your Company Inc.`;
    license_text     `All rights reserved.`;

Example output:

    Copyright (c) 2005 Your Company Inc.

    All rights reserved.

=item location

Base url for the application.  Normally, this applies only to httpd.conf
and things like it.  We need it here to generate tests.

=back

=head1 KEYWORDS in controller blocks

The simple statement keywords available in controller blocks are
(all of these are optional):

=over 4

=item controls_table

This is the name of the table which this controller controls.  It must
be defined in a table block somewhere in the bigtop file.

=item uses

A comma separated list of modules which the controller should include with
Perl use statements.  There is not currently a way to limit what these
modules export, except by editing the generated stub.

=item text_description

This is a short phrase that describes the rows of the table.  It will
usually become the return value of get_text_description (a class accessor).
For example, Gantry's AutoCRUD uses this in user messages.

=item rel_location

The location (URL suffix) relative to the base location of the application,
which will hit a given controller.  This keyword is primarily for httpd conf
and the like, but we need it here to generate tests.

=item location

The location (URL) which will hit a given controller.  This keyword is
primarily for httpd conf and the like, but we need it here to generate tests.

=back

Note that some other backend types also look for information in controller
blocks.  Pay particular attention to HttpdConf backends.  They typically
expect a location or rel_location keyword which becomes the Apache Location
for the controller.

=head1 METHODS for Control backends

=over 4

=item is_controller_keyword

Parameters: a word which might be a controller keyword

Returns: true if it is a controller keyword, false otherwise

=back

=head1 AUTHOR

Phil Crow <crow.phil@gmail.com>

=head1 COPYRIGHT and LICENSE

Copyright (C) 2005 by Phil Crow

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.

=cut