From: John Napiorkowski <jjnapiork@cpan.org>
Date: Wed, 8 Oct 2008 21:38:56 +0000 (+0000)
Subject: first checkin
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=3659fb05a2a60b93f41f4d564a669313d661b5fe;p=gitmo%2FMooseX-Dependent.git

first checkin
---

3659fb05a2a60b93f41f4d564a669313d661b5fe
diff --git a/specification.pod b/specification.pod
new file mode 100644
index 0000000..6269551
--- /dev/null
+++ b/specification.pod
@@ -0,0 +1,170 @@
+=head1 TITLE
+
+Specification - Technical details for dependent types
+
+=head1 DESCRIPTION
+
+Specification for extra, declaritive hinting to type constrain definitions.
+
+=head1 INTRODUCTION
+
+We'd like to be able to add additional 'hints' when declaring our type 
+constraints.  These hints would form an extention to the core types built into
+Moose, such as Str, Object, etc. as well as form the foundation for authors of
+Type Constraint extentions to also add these hints.  The idea is these hints
+would allow us to move a lot of the more common constraint types from the 
+where clause of a subtype to the subtype meta data.  This would make it simple
+to create a lot of the more common constraint types, improving usability and
+consistency.  Also, since the implementations for these constraints would be
+universally vetted, we are likely to improve global code quality.
+
+Additional advantages would be those derived from the common code ecosystem, 
+that is that more people would share common knowledge, improving our ability
+to build a strong community of shared best practices.
+
+Lastly, by hinting type constraints with additional metadata, the possibility
+to introspect that metadata usefully for code generation becomes possible.  In
+particular, we'd like these additional constraints to fit neatly with existing
+code generation and mapping tools, such asd DBIx-Class, Reaction, Ernst, etc.
+
+So, an important goal of choosing the hints to to choose and define ones that
+can be mapped to other type constraint systems.  For example, having a maximum
+length hint for a string type would map well to most database column types, 
+but a hint to match a string to a regular expression should be defined 
+carefully, since most databases have limited if any abilities to do this.
+
+Therefore, it will be important to make sure the hinting system can degrade or
+cast gracefully, that way hints defined at the application level will work
+neatly with those defined at a possible database level.
+
+=head1 USE CASES
+
+The following are possible use cases.
+
+=head2 Str
+
+It's common to add additional constraints to the STR type.  How many times have
+you done something like:
+
+	my $tc = subtype MaxStr10, as Str, where { length($_) <= 10 };
+
+To create a string of 10 characters or less.  Since this constraint is captured
+in the code block it is not introspecable.  A possible syntax to declare a Str
+type constraint with a maximum length hint might be:
+
+	my $tc = subtype MaxStr10, as Str[MaxLengthInclusive=>10];
+
+this information might be instrospectable via something like:
+
+	$tc->meta->hints->max_length_inclusive; ## returns 10
+
+=head2 DataTime and coercion possibilities
+
+The following example shows how this system could work to enhance type 
+constraints in the MooseX-Types* namespace.  It also shows how coercions could
+be hooked into the hint system to allow more finely tuned coercions:
+
+	use MooseX::Types::DateTime qw(DateTime);
+	
+	subtype USEasternDataTime,
+	 is DateTime[TimeZone=>'US/Eastern'];
+	 
+	coerce USEasternDataTime,
+	 from DateTime[TimeZone=>'Floating'];
+	 via {$_->timezone('US/Eastern')};
+	 
+The created subtype USEasternDataTime would only pass if the DateTime object
+has the defined timezone.  Their is a coercion that would adjust timezone
+information to the canonical type.
+
+=head2 Code generation and mapping
+
+Given a type constraint such as: 
+	
+	subtype MaxStr10, as Str[MaxLengthInclusive=>10];
+	
+That becomes part of a class definition:
+
+	package MyApp::Person;
+	...
+	has 'short_name' => (isa=>MaxStr10);
+
+A code generator or interpreter could introspect the metadata on the attribute
+'short_name' to create a table like:
+
+	CREATE TABLE Person (
+		short_name varchar(10)
+	);
+	
+[Addional Code examples to follow]
+	
+=head1 CORE TYPES AND HINT HEIRARCHY
+
+The following is an outline of the possible hints associated with core Moose
+type constraints.  Hints are assumed to be inherited.
+
+  Item[
+      Default
+      EqualTo
+      NotEqualTo
+  ]
+      Bool
+      Maybe[`a]
+      Undef
+      Defined
+          Value[
+              IsOneOf||IsNotOneOf
+              LessThanOrEqual || '<='
+              LessThan || '<'
+              GreaterThanOrEqual || '>='
+              GreaterThan || '>'
+              Between
+              NotBetween
+          ]
+              Num[
+              	Base
+                Precision
+                Scale
+DDUNCAN
+              ]
+                Int[
+                    Signed
+                    UnSigned
+                ]
+                    SmallInt
+                    BigInt
+              Str[
+                  ASCII*
+                  Printable*
+                  Word (must be a single 'word')
+                  MaxLength
+                  MinLength
+                EqualTo || 'eq'
+              ]
+
+	* Might be better as a general encoding type.
+	
+                ClassName[
+                    PackageBase (For stuff like '::Plugin::MyPlugin')
+                ]
+          Ref
+              ScalarRef
+              ArrayRef[`a][
+                  MaxElements
+                  MinElements
+              ]
+              HashRef[`a][
+                  HasAllKeys
+              ]
+              CodeRef
+              RegexpRef
+              GlobRef
+                FileHandle
+              Object[
+                  HasMethods
+                  ISA
+              ]
+                  Role[
+                      Requires
+                      Does
+                  ]