.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Declare::Constraints::Simple 3pm"
.TH Declare::Constraints::Simple 3pm "2018-03-31" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Declare::Constraints::Simple \- Declarative Validation of Data Structures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Declare::Constraints::Simple\-All;
\&
\&  my $profile = IsHashRef(
\&                    \-keys   => HasLength,
\&                    \-values => IsArrayRef( IsObject ));
\&
\&  my $result1 = $profile\->(undef);
\&  print $result1\->message, "\en";    # \*(AqNot a HashRef\*(Aq
\&
\&  my $result2 = $profile\->({foo => [23]});
\&
\&  print $result2\->message, "\en";    # \*(AqNot an Object\*(Aq
\&
\&  print $result2\->path, "\en";       
\&                    # \*(AqIsHashRef[val foo].IsArrayRef[0].IsObject\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The main purpose of this module is to provide an easy way to build a
profile to validate a data structure. It does this by giving you a set of
declarative keywords in the importing namespace.
.SH "USAGE"
.IX Header "USAGE"
This is just a brief intro. For details read the documents mentioned in
\&\*(L"\s-1SEE ALSO\*(R"\s0.
.SS "Constraint Import"
.IX Subsection "Constraint Import"
.Vb 1
\&  use Declare::Constraints::Simple\-All;
.Ve
.PP
The above command imports all constraint generators in the library into
the current namespace. If you want only a selection, use \f(CW\*(C`only\*(C'\fR:
.PP
.Vb 2
\&  use Declare::Constraints::Simple
\&      Only => qw(IsInt Matches And);
.Ve
.PP
You can find all constraints (and constraint-like generators, like
operators. In fact, \f(CW\*(C`And\*(C'\fR above is an operator. They're both implemented
equally, so the distinction is a merely philosophical one) documented in
the Declare::Constraints::Simple::Library pod. In that document you
will also find the exact parameters for their usage, so this here is just
a brief Intro and not a coverage of all possibilities.
.SS "Building a Profile"
.IX Subsection "Building a Profile"
You can use these constraints by building a tree that describes what data
structure you expect. Every constraint can be used as sub-constraint, as
parent, if it accepts other constraints, or stand-alone. If you'd just 
say
.PP
.Vb 2
\&  my $check = IsInt;
\&  print "yes!\en" if $check\->(23);
.Ve
.PP
it will work too. This also allows predefining tree segments, and nesting
them:
.PP
.Vb 1
\&  my $id_to_objects = IsArrayRef(IsObject);
.Ve
.PP
Here \f(CW$id_to_objects\fR would give it's \s-1OK\s0 on an array reference 
containing a list of objects. But what if we now decide that we actually 
want a hashref containing two lists of objects? Behold:
.PP
.Vb 4
\&  my $object_lists = 
\&    IsHashRef( HasAllKeys( qw(good bad) ),
\&               OnHashKeys( good => $id_to_objects,
\&                           bad  => $id_to_objects ));
.Ve
.PP
As you can see, constraints like \f(CW\*(C`IsArrayRef\*(C'\fR and \f(CW\*(C`IsHashRef\*(C'\fR allow you
to apply constraints to their keys and values. With this, you can step
down in the data structure.
.SS "Applying a Profile to a Data Structure"
.IX Subsection "Applying a Profile to a Data Structure"
Constraints return just code references that can be applied to one value
(and only one value) like this:
.PP
.Vb 1
\&  my $result = $object_lists\->($value);
.Ve
.PP
After this call \f(CW$result\fR contains a
Declare::Constraints::Simple::Result object. The first think one wants
to know is if the validation succeeded:
.PP
.Vb 1
\&  if ($result\->is_valid) { ... }
.Ve
.PP
This is pretty straight forward. To shorten things the result object also
overloads it's \f(CW\*(C`bool\*(C'\fRean context. This means you can alternatively
just say
.PP
.Vb 1
\&  if ($result) { ... }
.Ve
.PP
However, if the result indicates a invalid data structure, we have a few
options to find out what went wrong. There's a human parsable message in
the \f(CW\*(C`message\*(C'\fR accessor. You can override these by forcing it to a 
message in a subtree with the \f(CW\*(C`Message\*(C'\fR declaration. The \f(CW\*(C`stack\*(C'\fR 
contains the name of the chain of constraints up to the point of failure.
.PP
You can use the \f(CW\*(C`path\*(C'\fR accessor for a joined string path representing 
the stack.
.SS "Creating your own Libraries"
.IX Subsection "Creating your own Libraries"
You can declare a package as a library with
.PP
.Vb 1
\&  use Declare::Constraints::Simple\-Library;
.Ve
.PP
which will install the base class and helper methods to define
constraints. For a complete list read the documentation in
Declare::Constraints::Simple::Library::Base. You can use other
libraries as base classes to include their constraints in your export
possibilities. This means that with a package setup like
.PP
.Vb 3
\&  package MyLibrary;
\&  use warnings;
\&  use strict;
\&
\&  use Declare::Constraints::Simple\-Library;
\&  use base \*(AqDeclare::Constraints::Simple::Library\*(Aq;
\&
\&  constraint \*(AqMyConstraint\*(Aq,
\&    sub { return _result(($_[0] >= 12), \*(AqValue too small\*(Aq) };
\&
\&  1;
.Ve
.PP
you can do
.PP
.Vb 1
\&  use MyLibrary\-All;
.Ve
.PP
and have all constraints, from the default library and yours from above,
installed into your requesting namespace. You can override a constraint
just by redeclaring it in a subclass.
.SS "Scoping"
.IX Subsection "Scoping"
Sometimes you want to validate parts of a data structure depending on
another part of it. As of version 2.0 you can declare scopes and store
results in them. Here is a complete example:
.PP
.Vb 10
\&  my $constraint =
\&    Scope(\*(Aqfoo\*(Aq,
\&      And(
\&        HasAllKeys( qw(cmd data) ),
\&        OnHashKeys( 
\&          cmd => Or( SetResult(\*(Aqfoo\*(Aq, \*(Aqcmd_a\*(Aq,
\&                       IsEq(\*(AqFOO_A\*(Aq)),
\&                     SetResult(\*(Aqfoo\*(Aq, \*(Aqcmd_b\*(Aq,
\&                       IsEq(\*(AqFOO_B\*(Aq)) ),
\&          data => Or( And( IsValid(\*(Aqfoo\*(Aq, \*(Aqcmd_a\*(Aq),
\&                           IsArrayRef( IsInt )),
\&                      And( IsValid(\*(Aqfoo\*(Aq, \*(Aqcmd_b\*(Aq),
\&                           IsRegex )) )));
.Ve
.PP
This profile would accept a hash references with the keys \f(CW\*(C`cmd\*(C'\fR and
\&\f(CW\*(C`data\*(C'\fR. If \f(CW\*(C`cmd\*(C'\fR is set to \f(CW\*(C`FOO_A\*(C'\fR, then \f(CW\*(C`data\*(C'\fR has to be an array 
ref of integers. But if \f(CW\*(C`cmd\*(C'\fR is set to \f(CW\*(C`FOO_B\*(C'\fR, a regular expression 
is expected.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Declare::Constraints::Simple::Library, 
Declare::Constraints::Simple::Result,
Declare::Constraints::Simple::Base,
Module::Install
.SH "REQUIRES"
.IX Header "REQUIRES"
Carp::Clan, aliased, Class::Inspector, Scalar::Util,
overload and Test::More (for build).
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
Examples.
.IP "\(bu" 4
A list of questions that might come up, together with their answers.
.IP "\(bu" 4
A \f(CW\*(C`Custom\*(C'\fR constraint that takes a code reference.
.IP "\(bu" 4
Create stack objects that stringify to the current form, but can hold
more data.
.IP "\(bu" 4
Give the \f(CW\*(C`Message\*(C'\fR constraint the ability to get the generated 
constraint inserted in the message. A possibility would be to replace 
_\|_Value_\|_ and _\|_Message_\|_. It might also accept code references, which 
return strings.
.IP "\(bu" 4
Allow the \f(CW\*(C`IsCodeRef\*(C'\fR constraint to accept further constraints. One 
might like to check, for example, the refaddr of a closure.
.IP "\(bu" 4
A \f(CW\*(C`Captures\*(C'\fR constraint that takes a regex and can apply other
constraints to the matches.
.IP "\(bu" 4
???
.IP "\(bu" 4
Profit.
.SH "INSTALLATION"
.IX Header "INSTALLATION"
.Vb 4
\&  perl Makefile.PL
\&  make
\&  make test
\&  make install
.Ve
.PP
For details read Module::Install.
.SH "AUTHOR"
.IX Header "AUTHOR"
Robert 'phaylon' Sedlacek \f(CW\*(C`<phaylon@dunkelheit.at>\*(C'\fR
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This module is free software, you can redistribute it and/or modify it 
under the same terms as perl itself.