[Jifty-commit] r552 - in Jifty-DBI/trunk: lib/Jifty/DBI
jifty-commit at lists.jifty.org
jifty-commit at lists.jifty.org
Mon Feb 6 22:26:52 EST 2006
Author: alexmv
Date: Mon Feb 6 22:26:51 2006
New Revision: 552
Modified:
Jifty-DBI/trunk/ (props changed)
Jifty-DBI/trunk/META.yml
Jifty-DBI/trunk/lib/Jifty/DBI/Column.pm
Jifty-DBI/trunk/lib/Jifty/DBI/Filter.pm
Jifty-DBI/trunk/lib/Jifty/DBI/Handle.pm
Jifty-DBI/trunk/lib/Jifty/DBI/Record.pm
Jifty-DBI/trunk/lib/Jifty/DBI/Schema.pm
Jifty-DBI/trunk/lib/Jifty/DBI/SchemaGenerator.pm
Log:
r8961 at zoq-fot-pik: chmrr | 2006-02-06 22:25:57 -0500
* Doc fixes
Modified: Jifty-DBI/trunk/META.yml
==============================================================================
--- Jifty-DBI/trunk/META.yml (original)
+++ Jifty-DBI/trunk/META.yml Mon Feb 6 22:26:51 2006
@@ -2,7 +2,7 @@
DBD::SQLite: 0
Test::More: 0.52
distribution_type: module
-generated_by: Module::Install version 0.50
+generated_by: Module::Install version 0.52
license: perl
name: Jifty-DBI
no_index:
@@ -26,4 +26,4 @@
Lingua::EN::Inflect: 0
UNIVERSAL::require: 0
perl: 5.8.3
-version: 0.09
+version: 0.11
Modified: Jifty-DBI/trunk/lib/Jifty/DBI/Column.pm
==============================================================================
--- Jifty-DBI/trunk/lib/Jifty/DBI/Column.pm (original)
+++ Jifty-DBI/trunk/lib/Jifty/DBI/Column.pm Mon Feb 6 22:26:51 2006
@@ -16,7 +16,6 @@
length
mandatory
virtual
- distinct
refers_to by
alias_for_column
since until
Modified: Jifty-DBI/trunk/lib/Jifty/DBI/Filter.pm
==============================================================================
--- Jifty-DBI/trunk/lib/Jifty/DBI/Filter.pm (original)
+++ Jifty-DBI/trunk/lib/Jifty/DBI/Filter.pm Mon Feb 6 22:26:51 2006
@@ -14,11 +14,14 @@
=item value_ref
-A reference to the current value you're going to be massaging. C<encode> works in place, massaging whatever value_ref refers to.
+A reference to the current value you're going to be
+massaging. C<encode> works in place, massaging whatever value_ref
+refers to.
=item column
-A L<Jifty::DBI::Column> object, whatever sort of column we're working with here.
+A L<Jifty::DBI::Column> object, whatever sort of column we're working
+with here.
=back
@@ -61,9 +64,10 @@
=head2 decode
-C<decode> takes data that the database is handing back to us and gets it into a form that's OK to hand back to the user. This could be anything
-from flattening a L<DateTime> object into an ISO date to making sure
-that data is utf8 clean.
+C<decode> takes data that the database is handing back to us and gets
+it into a form that's OK to hand back to the user. This could be
+anything from flattening a L<DateTime> object into an ISO date to
+making sure that data is utf8 clean.
=cut
Modified: Jifty-DBI/trunk/lib/Jifty/DBI/Handle.pm
==============================================================================
--- Jifty-DBI/trunk/lib/Jifty/DBI/Handle.pm (original)
+++ Jifty-DBI/trunk/lib/Jifty/DBI/Handle.pm Mon Feb 6 22:26:51 2006
@@ -250,7 +250,7 @@
Returns the current SQL statement log as an array of arrays. Each entry is a triple of
-(Time, Statement, Duration)
+(Time, Statement, [Bindings], Duration)
=cut
Modified: Jifty-DBI/trunk/lib/Jifty/DBI/Record.pm
==============================================================================
--- Jifty-DBI/trunk/lib/Jifty/DBI/Record.pm (original)
+++ Jifty-DBI/trunk/lib/Jifty/DBI/Record.pm Mon Feb 6 22:26:51 2006
@@ -383,7 +383,8 @@
=item after_I<column_name>
-This hook is called with a reference to the value returned by Jifty::DBI. Its return value is discarded.
+This hook is called with a reference to the value returned by
+Jifty::DBI. Its return value is discarded.
=back
@@ -393,7 +394,8 @@
=item before_set_I<column_name> PARAMHASH
-C<Jifty::DBI::Record> passes this function a reference to a paramhash composed of:
+C<Jifty::DBI::Record> passes this function a reference to a paramhash
+composed of:
=over
@@ -407,7 +409,8 @@
=item is_sql_function
-A boolean that, if true, indicates that I<value> is an SQL function, not just a value.
+A boolean that, if true, indicates that I<value> is an SQL function,
+not just a value.
=back
@@ -423,7 +426,6 @@
value. (The Jifty application framework uses this as part of its AJAX
validation system.)
-
=back
@@ -817,12 +819,16 @@
=item before_create
-This method is called before trying to create our row in the database. It's handed a reference to your paramhash. (That means it can modify your parameters on the fly). C<before_create> returns a true or false value. If it returns false, the create is aborted.
+This method is called before trying to create our row in the
+database. It's handed a reference to your paramhash. (That means it
+can modify your parameters on the fly). C<before_create> returns a
+true or false value. If it returns false, the create is aborted.
=item after_create
-This method is called after attempting to insert the record into the database. It gets handed a reference to the return value of the insert. That'll either be a true value or a L<Class::ReturnValue>
-
+This method is called after attempting to insert the record into the
+database. It gets handed a reference to the return value of the
+insert. That'll either be a true value or a L<Class::ReturnValue>
=back
@@ -887,12 +893,14 @@
=item before_delete
-This method is called before the record deletion, if it exists. It returns a boolean value. If the return value is false, it aborts the create and returns the return value from the hook.
+This method is called before the record deletion, if it exists. It
+returns a boolean value. If the return value is false, it aborts the
+create and returns the return value from the hook.
=item after_delete
-This method is called after deletion, with a reference to the return value
-from the delete operation.
+This method is called after deletion, with a reference to the return
+value from the delete operation.
=back
Modified: Jifty-DBI/trunk/lib/Jifty/DBI/Schema.pm
==============================================================================
--- Jifty-DBI/trunk/lib/Jifty/DBI/Schema.pm (original)
+++ Jifty-DBI/trunk/lib/Jifty/DBI/Schema.pm Mon Feb 6 22:26:51 2006
@@ -3,13 +3,57 @@
package Jifty::DBI::Schema;
+=head1 NAME
+
+Jifty::DBI::Schema - Use a simple syntax to describe a Jifty table.
+
+=head1 SYNOPSIS
+
+package Wifty::Model::Page::Schema;
+use Jifty::DBI::Schema;
+
+=cut
+
+=head1 DESCRIPTION
+
+Each Jifty Application::Model::Class module describes a record class
+for for a Jifty application. Each column statement sets out the name
+and attributes used to describe the column in a backend database, in
+user interfaces, and other contexts. For example:
+
+ column content =>
+ type is 'text',
+ label is 'Content',
+ render_as 'textarea';
+
+defines a column called "content" that is of type "text". It will be
+rendered with the label "Content" (note the capital) and as a "textarea" in
+a HTML form.
+
+Jifty::DBI::Schema builds a L<Jifty::DBI::Column>. That class defines
+other attributes for database structure that are not exposed directly
+here. One example of this is the "refers_to" method used to create
+associations between classes.
+
+=cut
+
use Carp qw/carp/;
use Exporter::Lite;
our @EXPORT
- = qw(column type default validator immutable unreadable length distinct mandatory not_null valid_values label hints render_as since input_filters output_filters is by are on virtual);
+ = qw(column type default validator immutable unreadable length mandatory not_null valid_values label hints render_as since input_filters output_filters is by are on virtual);
our $SCHEMA;
+=head1 FUNCTIONS
+
+All these functions are exported.
+
+=head2 column
+
+Set forth the description of a column in the data store.
+
+=cut
+
sub column {
my $name = lc(shift);
@@ -48,6 +92,7 @@
$virtual_column->alias_for_column($name);
}
$column->by('id') unless $column->by;
+ $column->type('integer') unless $column->type;
} elsif ( UNIVERSAL::isa( $refclass, 'Jifty::DBI::Collection' ) ) {
$column->by('id') unless $column->by;
$column->virtual('1');
@@ -55,91 +100,226 @@
warn "Error: $refclass neither Record nor Collection";
}
} else {
- $column->type('varchar(255)') unless ($column->type);
+ $column->type('varchar(255)') unless $column->type;
}
$from->COLUMNS->{$name} = $column;
}
+=head2 type
+
+type passed to our database abstraction layer, which should resolve it
+to a database-specific type. Correct usage is C<type is 'text'>.
+
+=cut
+
sub type ($) {
_list( type => shift );
+
}
+=head2 default
+
+Give a default value for the column. Correct usage is C<default is
+'foo'>.
+
+=cut
+
sub default ($) {
_list( default => shift );
}
+=head2 validator
+
+Defines a subroutine which returns a true value only for valid values
+this column can have. Correct usage is C<validator is \&foo>.
+
+=cut
+
sub validator ($) {
_list( validator => shift );
}
+=head2 immutable
+
+States that this column is not writable. This is useful for
+properties that are set at creation time but not modifiable
+thereafter, like 'created by'. Correct usage is C<is immutable>.
+
+=cut
+
sub immutable () {
_item( [ writable => 0 ] );
}
+=head2 unreadable
+
+States that this column is not directly readable by the application
+using C<< $record->column >>; this is useful for password columns and
+the like. The data is still accessible via C<< $record->_value('') >>.
+Correct usage is C<is unreadable>.
+
+=cut
+
sub unreadable {
_item( [ readable => 0 ] );
}
+=head2 length
+
+Sets a maximum length to store in the database; values longer than
+this are truncated before being inserted into the database, using
+L<Jifty::DBI::Filter::Truncate>. Note that this is in B<bytes>, not
+B<characters>. Correct usage is C<length is 42>.
+
+=cut
+
sub length ($) {
_list( length => shift );
}
+=head2 mandatory
+
+Mark as a required. May be used for generating user interfaces.
+Correct usage is C<is mandatory>.
+
+=cut
+
sub mandatory () {
_item( [ mandatory => 1 ] );
}
-sub distinct () {
- _item( [ distinct => 1 ] );
-}
+=head2 not_null
+
+Same as L</mandatory>. This is depricated. Currect usage would be
+C<is not_null>.
+
+=cut
sub not_null () {
carp "'is not_null' is deprecated in favor of 'is mandatory'";
_item( [ mandatory => 1 ] );
}
+=head2 input_filters
+
+Sets a list of input filters on the data. Correct usage is
+C<input_filters are 'Jifty::DBI::Filter::DateTime'>. See
+L<Jifty::DBI::Filter>.
+
+=cut
+
sub input_filters ($) {
_list( input_filters => shift );
}
+=head2 output_filters
+
+Sets a list of output filters on the data. Correct usage is
+C<input_filters are 'Jifty::DBI::Filter::DateTime'>. See
+L<Jifty::DBI::Filter>.
+
+=cut
+
sub output_filters ($) {
_list( output_filters => shift );
}
+=head2 since
+
+What application version this column was last changed. Correct usage
+is C<since '0.1.5'>.
+
+=cut
+
sub since ($) {
_list( since => shift );
}
+=head2 valid_values
+
+A list of valid values for this column. Jifty will use this to
+autoconstruct a validator for you. This list may also be used to
+generate the user interface. Correct usage is C<valid_values are
+qw/foo bar baz/>.
+
+=cut
+
sub valid_values ($) {
_list( valid_values => shift );
}
+=head2 label
+
+Designates a human-readable label for the column, for use in user
+interfaces. Correct usage is C<label is 'Your foo value'>.
+
+=cut
+
sub label ($) {
_list( label => shift );
}
+=head2 hints
+
+A sentence or two to display in long-form user interfaces about what
+might go in this column. Correct usage is C<hints is 'Used by the
+frobnicator to to strange things'>.
+
+=cut
+
sub hints ($) {
_list( hints => shift );
}
+=head2 render_as
+
+Used in user interface generation to know how to render the column.
+
+=cut
+
sub render_as ($) {
_list( render_as => shift );
}
+=head2 is
+
+Helper method to improve readability.
+
+=cut
+
sub is ($) {
my $thing = shift;
ref $thing eq "ARRAY" ? _list( @{$thing} ) : _item($thing);
}
+=head2 by
+
+Helper method to improve readability.
+
+=cut
+
sub by ($) {
_list( by => shift );
}
+=head2 are
+
+Helper method to improve readability.
+
+=cut
+
sub are (@) {
_item( [@_] );
}
+=head2 on
+
+Helper method to improve readability.
+
+=cut
+
sub on ($) {
_list( self => shift );
}
@@ -161,4 +341,19 @@
$_[0];
}
+=head1 EXAMPLE
+
+=head1 AUTHOR
+
+=head1 BUGS
+
+=head1 SUPPORT
+
+=head1 COPYRIGHT & LICENSE
+
+This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=cut
+
1;
Modified: Jifty-DBI/trunk/lib/Jifty/DBI/SchemaGenerator.pm
==============================================================================
--- Jifty-DBI/trunk/lib/Jifty/DBI/SchemaGenerator.pm (original)
+++ Jifty-DBI/trunk/lib/Jifty/DBI/SchemaGenerator.pm Mon Feb 6 22:26:51 2006
@@ -200,7 +200,6 @@
{ name => $column->name,
type => $column->type,
null => $column->mandatory ? 0 : 1,
- distinct => $column->distinct,
default => $column->default,
}
);
More information about the Jifty-commit
mailing list