[Rt-commit] r5596 - in Object-Declare: lib/Object

[audreyt at bestpractical.com]

Author: audreyt
Date: Mon Jul 17 22:06:22 2006
New Revision: 5596

Modified:
   Object-Declare/Changes
   Object-Declare/README
   Object-Declare/lib/Object/Declare.pm

Log:
* This be 0.06.
* Documentation cleanup; no functional changes.

Modified: Object-Declare/Changes
==============================================================================
--- Object-Declare/Changes	(original)
+++ Object-Declare/Changes	Mon Jul 17 22:06:22 2006
@@ -1,3 +1,7 @@
+[Changes for 0.06 - 2006-07-17]
+
+* Documentation cleanup; no functional changes.
+
 [Changes for 0.05 - 2006-07-17]
 
 * Support for ordered declarations, via list-context return of 

Modified: Object-Declare/README
==============================================================================
--- Object-Declare/README	(original)
+++ Object-Declare/README	Mon Jul 17 22:06:22 2006
@@ -4,7 +4,7 @@
 SYNOPSIS
         use Object::Declare ['MyApp::Column', 'MyApp::Param'];
 
-        my $objects = declare {
+        my %objects = declare {
 
         param foo =>
             is immutable,
@@ -16,14 +16,18 @@
 
         };
 
-        print $objects->{foo}; # a MyApp::Param object
-        print $objects->{bar}; # a MyApp::Column object
+        print $objects{foo}; # a MyApp::Param object
+        print $objects{bar}; # a MyApp::Column object
 
 DESCRIPTION
     This module exports one function, "declare", for building named objects
     with a declarative syntax, similar to how Jifty::DBI::Schema defines its
     columns.
 
+    In list context, "declare" returns a list of name/object pairs in the
+    order of declaration (allowing duplicates), suitable for putting into a
+    hash. In scalar context, "declare" returns a hash reference.
+
     Using a flexible "import" interface, one can change exported helper
     functions names (*declarator*), words to link labels and values together
     (*copula*), and the table of named classes to declare (*mapping*):

Modified: Object-Declare/lib/Object/Declare.pm
==============================================================================
--- Object-Declare/lib/Object/Declare.pm	(original)
+++ Object-Declare/lib/Object/Declare.pm	Mon Jul 17 22:06:22 2006
@@ -1,5 +1,5 @@
 package Object::Declare;
-$Object::Declare::VERSION = '0.05';
+$Object::Declare::VERSION = '0.06';
 
 use 5.006;
 use strict;
@@ -32,23 +32,23 @@
         $copula = [$copula];
     }
 
-    {
-        no strict 'refs';
-        *{"$from\::$_"} = sub (&) {
-            unshift @_, ($mapping, $copula);
-            goto &_declare;
-        } for @$declarator;
-        *{"$from\::$_"} = \&{"$from\::$_"} for keys %$mapping;
-        *{"UNIVERSAL::$_"} = \&{"UNIVERSAL::$_"} for @$copula;
-        *{"$_\::AUTOLOAD"} = \&{"$_\::AUTOLOAD"} for @$copula;
-    }
+    no strict 'refs';
+
+    # Install declarator functions into caller's package
+    *{"$from\::$_"} = sub (&) {
+        unshift @_, ($mapping, $copula);
+        goto &_declare;
+    } for @$declarator;
+
+    # Establish prototypes (same as "use subs") so Sub::Override can work
+    *{"$from\::$_"}     = \&{"$from\::$_"} for keys %$mapping;
+    *{"UNIVERSAL::$_"}  = \&{"UNIVERSAL::$_"} for @$copula;
+    *{"$_\::AUTOLOAD"}  = \&{"$_\::AUTOLOAD"} for @$copula;
 }
 
-sub _declare (&) {
-    my $mapping = shift;
-    my $copula  = shift;
-    my $code    = shift;
-    my $from    = caller;
+sub _declare {
+    my ($mapping, $copula, $code) = @_;
+    my $from = caller;
 
     # Table of collected objects.
     my @objects;
@@ -59,23 +59,29 @@
 
     # in DSL mode; install &AUTOLOAD to collect all unrecognized calls
     # into a katamari structure and analyze it later.
-    $override->replace("UNIVERSAL::$_" => \&_universal) for @$copula;
-    $override->replace("$_\::AUTOLOAD" => \&_autoload) for @$copula;
-    $override->replace(
-        "$from\::$_" => _make_object($mapping->{$_} => \@objects)
-    ) for keys %$mapping;
+    foreach my $sym (@$copula) {
+        $override->replace("UNIVERSAL::$sym" => \&_universal);
+        $override->replace("$sym\::AUTOLOAD" => \&_autoload);
+    }
+
+    while (my ($sym, $class) = each %$mapping) {
+        $override->replace("$from\::$sym" => _make_object($class => \@objects));
+    }
 
     # Let's play katamari!
     $code->();
 
+    # In scalar context, returns hashref; otherwise preserve ordering
     return(wantarray ? @objects : { @objects });
 }
 
+# Turn "is some_field" into "some_field is 1"
 sub _universal {
     push @_, 1;
     bless(\@_, 'Object::Declare::Katamari');
 }
 
+# Handle "some_field is $some_value"
 sub _autoload {
     shift;
     my $field = our $AUTOLOAD;
@@ -84,7 +90,7 @@
     bless(\@_, 'Object::Declare::Katamari');
 }
 
-# Make a Star from the katamari!
+# Make a star from the katamari!
 sub _make_object {
     my ($class, $schema) = @_;
 
@@ -105,11 +111,11 @@
         while ref($katamari[-1]) eq __PACKAGE__; 
 
     if (@katamari == 1) {
-        # Singular value
+        # single value: "is foo"
         return($field => @katamari, @unrolled);
     }
     else {
-        # Plural value
+        # Multiple values: "are qw( foo bar baz )"
         return($field => \@katamari, @unrolled);
     }
 }
@@ -138,8 +144,8 @@
 
     };
 
-    print $objects->{foo}; # a MyApp::Param object
-    print $objects->{bar}; # a MyApp::Column object
+    print $objects{foo}; # a MyApp::Param object
+    print $objects{bar}; # a MyApp::Column object
 
 =head1 DESCRIPTION