1. Toby Inkster
  2. p5-type-tiny

Commits

Toby Inkster  committed 01c03c8

apply same documentation layout to Type::Coercion

  • Participants
  • Parent commits 4b7a4dc
  • Branches default

Comments (0)

Files changed (2)

File lib/Type/Coercion.pm

View file
  • Ignore whitespace
 
 =head2 Attributes
 
+Attributes are named values that may be passed to the constructor. For
+each attribute, there is a corresponding reader method. For example:
+
+   my $c = Type::Coercion->new( type_constraint => Int );
+   my $t = $c->type_constraint;  # Int
+
+=head3 Important attributes
+
+These are the attributes you are likely to be most interested in
+providing when creating your own type coercions, and most interested
+in reading when dealing with coercion objects.
+
 =over
 
+=item C<type_constraint>
+
+Weak reference to the target type constraint (i.e. the type constraint which
+the output of coercion coderefs is expected to conform to).
+
+=item C<type_coercion_map>
+
+Arrayref of source-type/code pairs. Don't set this in the constructor; use
+the C<add_type_coercions> method instead.
+
+=item C<frozen>
+
+Boolean; default false. A frozen coercion cannot have C<add_type_coercions>
+called upon it.
+
 =item C<name>
 
 A name for the coercion. These need to conform to certain naming
 Optional. Informational only: setting this attribute does not install
 the coercion into the package.
 
-=item C<type_constraint>
+=back
 
-Weak reference to the target type constraint (i.e. the type constraint which
-the output of coercion coderefs is expected to conform to).
+=head3 Attributes related to parameterizable and parameterized types
 
-=item C<type_coercion_map>
+The following attributes are used for parameterized coercions, but are not
+fully documented because they may change in the near future:
 
-Arrayref of source-type/code pairs. Don't set this in the constructor; use
-the C<add_type_coercions> method instead.
+=over
+
+=item C<< coercion_generator >>
+
+=item C<< parameters >>
+
+=item C<< parameterized_from >>
+
+=back
+
+=head3 Lazy generated attributes
+
+The following attributes should not be usuallly passed to the constructor;
+unless you're doing something especially unusual, you should rely on the
+default lazily-built return values.
+
+=over
 
 =item C<< compiled_coercion >>
 
 A L<Moose::Meta::TypeCoercion> object equivalent to this one. Don't set this
 manually; rely on the default built one.
 
-=item C<frozen>
-
-Boolean; default false. A frozen coercion cannot have C<add_type_coercions>
-called upon it.
-
 =back
 
 =head2 Methods
 
+=head3 Predicate methods
+
+These methods return booleans indicating information about the coercion.
+They are each tightly associated with a particular attribute.
+(See L</"Attributes">.)
+
 =over
 
 =item C<has_type_constraint>, C<has_library>
 
 Returns true iff the coercion does not have a C<name>.
 
-=item C<< qualified_name >>
+=back
 
-For non-anonymous coercions that have a library, returns a qualified
-C<< "Library::Type" >> sort of name. Otherwise, returns the same as C<name>.
+The following predicates are used for parameterized coercions, but are not
+fully documented because they may change in the near future:
 
-=item C<< add_type_coercions($type1, $code1, ...) >>
+=over
 
-Takes one or more pairs of L<Type::Tiny> constraints and coercion code,
-creating an ordered list of source types and coercion codes.
+=item C<< has_coercion_generator >>
 
-Coercion codes can be expressed as either a string of Perl code (this
-includes objects which overload stringification), or a coderef (or object
-that overloads coderefification). In either case, the value to be coerced
-is C<< $_ >>.
+=item C<< has_parameters >>
+
+=item C<< is_parameterizable >>
+
+=item C<< is_parameterized >>
+
+=back
+
+=head3 Coercion
+
+The following methods are used for coercing values to a type constraint:
+
+=over
 
 =item C<< coerce($value) >>
 
 
 Returns the coerced value.
 
+=back
+
+=head3 Coercion code definition methods
+
+=over
+
+=item C<< add_type_coercions($type1, $code1, ...) >>
+
+Takes one or more pairs of L<Type::Tiny> constraints and coercion code,
+creating an ordered list of source types and coercion codes.
+
+Coercion codes can be expressed as either a string of Perl code (this
+includes objects which overload stringification), or a coderef (or object
+that overloads coderefification). In either case, the value to be coerced
+is C<< $_ >>.
+
+=item C<< freeze >>
+
+Sets the C<frozen> attribute to true. There is no C<unfreeze>. Called
+automatically by L<Type::Tiny> sometimes.
+
+=back
+
+=head3 Parameterization
+
+The following method is used for parameterized coercions, but is not
+fully documented because it may change in the near future:
+
+=over
+
+=item C<< parameterize(@params) >>
+
+=back
+
+=head3 Type coercion introspection methods
+
+These methods allow you to determine a coercion's relationship to type
+constraints:
+
+=over
+
 =item C<< has_coercion_for_type($source_type) >>
 
 Returns true iff this coercion has a coercion from the source type.
 actually be necessary for this value (due to it already meeting the target
 type constraint).
 
+=back
+
+The C<type_constraint> attribute provides a type constraint object for the
+target type constraint of the coercion. See L</"Attributes">.
+
+=head3 Inlining methods
+
+The following methods are used to generate strings of Perl code which
+may be pasted into stringy C<eval>uated subs to perform type coercions:
+
+=over
+
 =item C<< can_be_inlined >>
 
 Returns true iff the coercion can be inlined.
 
 Much like C<inline_coerce> from L<Type::Tiny>.
 
-=item C<< freeze >>
+=back
 
-Set C<frozen> to true. There is no C<unfreeze>. Called automatically by
-L<Type::Tiny> sometimes.
+=head3 Other methods
+
+=over
+
+=item C<< qualified_name >>
+
+For non-anonymous coercions that have a library, returns a qualified
+C<< "MyLib::MyCoercion" >> sort of name. Otherwise, returns the same
+as C<name>.
 
 =item C<< isa($class) >>, C<< can($method) >>, C<< AUTOLOAD(@args) >>
 
 
 =back
 
-The following methods are used for parameterized coercions, but are not
-fully documented because they may change in the near future:
-
-=over
-
-=item C<< coercion_generator >>
-
-=item C<< has_coercion_generator >>
-
-=item C<< has_parameters >>
-
-=item C<< is_parameterizable >>
-
-=item C<< is_parameterized >>
-
-=item C<< parameterize(@params) >>
-
-=item C<< parameters >>
-
-=item C<< parameterized_from >>
-
-=back
-
 The following methods exist for Moose/Mouse compatibility, but do not do
 anything useful.
 

File lib/Type/Tiny.pm

View file
  • Ignore whitespace
 =head3 Important attributes
 
 These are the attributes you are likely to be most interested in
-proviing when creating your own type constraints, and most interested
+providing when creating your own type constraints, and most interested
 in reading when dealing with type constraint objects.
 
 =over
 
 =back
 
-=head3 Child type constraint creation
+=head3 Child type constraint creation and parameterization
 
 These methods generate new type constraint objects that inherit from the
 constraint they are called upon: