[Bps-public-commit] r14787 - in Prophet/trunk: .
spang at bestpractical.com
spang at bestpractical.com
Tue Aug 5 13:02:59 EDT 2008
Author: spang
Date: Tue Aug 5 13:02:59 2008
New Revision: 14787
Modified:
Prophet/trunk/ (props changed)
Prophet/trunk/lib/Prophet/Record.pm
Log:
r47668 at loki: spang | 2008-08-05 17:52:41 +0100
omg pod for Prophet::Record
Modified: Prophet/trunk/lib/Prophet/Record.pm
==============================================================================
--- Prophet/trunk/lib/Prophet/Record.pm (original)
+++ Prophet/trunk/lib/Prophet/Record.pm Tue Aug 5 13:02:59 2008
@@ -13,7 +13,7 @@
=head1 DESCRIPTION
-This class represents a base class for any record in a Prophet database
+This class represents a base class for any record in a Prophet database.
=cut
@@ -54,31 +54,50 @@
is => 'rw',
isa => 'HashRef',
default => sub { {} },
+ documentation => 'A hash of accessor_name => collection_class references.',
);
class_has PROPERTIES => (
is => 'rw',
isa => 'HashRef',
default => sub { {} },
+ documentation => 'A hash of properties that a record class declares.',
);
-sub declared_props {
- return sort keys %{ $_[0]->PROPERTIES };
-}
-
my $UUIDGEN = Data::UUID->new();
-sub record_type { $_[0]->type }
-
=head1 METHODS
=head2 new { handle => Prophet::Replica, type => $type }
Instantiates a new, empty L<Prophet::Record/> of type $type.
+=head2 declared_props
+
+Returns a sorted list of the names of the record's declared properties.
+Declared properties are always validated even if the user provides no value
+for that prop. This can be used for such things as requiring records to
+have certain props in order to be created, for example.
+
+=cut
+
+sub declared_props {
+ return sort keys %{ $_[0]->PROPERTIES };
+}
+
+=head2 record_type
+
+Returns the record's type.
+
=cut
-=head2 register_reference
+sub record_type { $_[0]->type }
+
+=head2 register_reference $class, $accessor, $foreign_class, @args
+
+Registers a reference to a foreign class to this record. The
+foreign class must be of type L<Prophet::Collection> or
+L<Prophet::Record>, or else a fatal error is triggered.
=cut
@@ -100,9 +119,9 @@
=head2 register_collection_reference $accessor, $collection_class, by => $key_in_model
-Registers and create accessor in current class the associated
+Registers and creates an accessor in the current class to the associated
collection C<$collection_class>, which refers to the current class by
-$key_in_model in the model class of $collection_class.
+C<$key_in_model> in the model class of C<$collection_class>.
=cut
@@ -223,7 +242,7 @@
In case of failure, returns false.
-On success, returns ____
+On success, returns true.
=cut
@@ -305,6 +324,14 @@
}
+=head2 changesets
+
+Returns an ordered list of changeset objects for all changesets containing
+changes to the record specified by this record object.
+
+Note that changesets may include changes to other records.
+
+=cut
sub changesets {
my $self = shift;
@@ -314,6 +341,13 @@
);
}
+=head2 changes
+
+Returns an ordered list of all the change objects that represent changes
+to the record specified by this record object.
+
+=cut
+
sub changes {
my $self = shift;
my $uuid = $self->uuid;
@@ -324,10 +358,31 @@
@changesets;
}
+=head2 uniq @list
+
+The C<List::MoreUtils::uniq> function (taken from version 0.21).
+
+Returns a new list by stripping duplicate values in @list. The order of
+elements in the returned list is the same as in @list. In scalar
+context, returns the number of unique elements in @list.
+
+ my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
+ my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
+
+=cut
-# uniq ganked from List::MoreUtils 0.21
sub uniq (@) { my %h; map { $h{$_}++ == 0 ? $_ : () } @_; }
+=head2 validate_props $propsref
+
+Takes a reference to a props hash and validates each prop in the
+hash or in the C<PROPERTIES> attribute that has a validation routine
+(C<validate_prop_$prop>).
+
+Dies if any prop fails validation. Returns true on success. Returns
+false if any prop is not allowable (prop name fails validation).
+
+=cut
sub validate_props {
my $self = shift;
@@ -347,8 +402,25 @@
return 1;
}
+=head2 _validate_prop_name
+
+A hook to allow forcing users to only use certain prop names.
+
+Currently just returns true for all inputs.
+
+=cut
+
sub _validate_prop_name {1}
+=head2 canonicalize_props $propsref
+
+Takes a hashref to a props hash and canonicalizes each one if a
+C<canonicalize_prop_$prop> routine is available.
+
+Returns true on completion.
+
+=cut
+
sub canonicalize_props {
my $self = shift;
my $props = shift;
@@ -364,7 +436,8 @@
=head2 default_props $props_ref
Takes a reference to a hash of props and looks up the defaults for those
-props, if they exist. Sets the values of the props in the hash to the defaults.
+props, if they exist (by way of C<default_prop_$prop> routines). Sets the
+values of the props in the hash to the defaults.
=cut
@@ -385,15 +458,32 @@
return 1;
}
-=head2 format_summary
+=head2 _default_summary_format
-returns a formatted string that is the summary for the record.
+A string of the default summary format for record types that do not
+define their own summary format.
-=cut
+A summary format should consist of format_string,field pairs, separated
+by | characters.
+
+Fields that are not property names must start with the C<$> character and be
+handled in the C<atom_value> routine.
+Example:
+
+C<'%s,$luid | %s,summary | %s,status'>
+
+=cut
sub _default_summary_format { 'No summary format defined for this record type' }
+=head2 _summary_format
+
+Tries to find the summary format for the record type. Returns
+L<_default_summary_format> if nothing better can be found.
+
+=cut
+
sub _summary_format {
my $self = shift;
return $self->app_handle->config->get('summary_format_'.$self->type)
@@ -401,15 +491,45 @@
|| $self->_default_summary_format;
}
+=head2 _atomize_summary_format [$format]
+
+Splits a summary format into pieces (separated by arbitrary whitespace and
+the | character). Returns the split list.
+
+If no summary format is supplied, this routine attempts to find one by
+calling L<_summary_format>.
+
+=cut
+
sub _atomize_summary_format {
my $self = shift;
my $format = shift || $self->_summary_format;
return split /\s*\|\s*/, $format;
}
+=head2 _parse_summary_format
+
+Parses the summary format for this record's type (or the default summary
+format if no type-specific format exists).
+
+Returns a list of hashrefs to hashes which contain the following keys:
+C<format>, C<prop>, C<value>, and C<formatted>
+
+(These are the format string, the property to be formatted, the value
+of that property, and the atom formatted according to C<format_atom>,
+respectively.)
+
+If no format string is supplied in a given format atom, C<%s> is used.
+
+If a format atom C<$value>'s value does not start with a C<$> character, it is
+swapped with the value of the prop C<$value> (or the string "(no value)".
+
+All values are filtered through the function C<atom_value>.
+
+=cut
+
sub _parse_format_summary {
my $self = shift;
- my $format = shift;
my $props = $self->get_props;
@@ -443,6 +563,13 @@
return @out;
}
+=head2 format_summary
+
+Returns a formatted string that is the summary for the record. In an
+array context, returns a list of
+
+=cut
+
sub format_summary {
my $self = shift;
@@ -451,6 +578,17 @@
return join ' ', map { $_->{formatted} } @out;
}
+=head2 atom_value $value_in
+
+Takes an input value from a summary format atom and returns either its
+output value or itself (because it is a property and its value should be
+retrieved from the props attribute instead).
+
+For example, an input value of "$uuid" would return the record object's
+C<uuid> field.
+
+=cut
+
sub atom_value {
my $self = shift;
my $value_in = shift;
@@ -464,6 +602,12 @@
return $value_in;
}
+=head2 format_atom $string => $value
+
+Takes a format string / value pair and returns a formatted string for printing.
+
+=cut
+
sub format_atom {
my $self = shift;
my $string = shift;
@@ -484,8 +628,13 @@
return $luid;
}
+=head2 colorize $field, $value
+Colorizes the given property / value pair according to the field's
+own C<color_prop_$field> routine, or else the generic L<color_prop> routine
+if a specific routine does not exist.
+=cut
sub colorize {
my $self = shift;
More information about the Bps-public-commit
mailing list