{
    "mode": "perldoc",
    "parameter": "Specio::Constraint::Simple",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Specio%3A%3AConstraint%3A%3ASimple/json",
    "generated": "2026-06-11T18:11:56Z",
    "synopsis": "my $str = t('Str');\nprint $str->name; # Str\nmy $parent = $str->parent;\nif ( $str->valueisvalid($value) ) { ... }\n$str->validateordie($value);\nmy $code = $str->inlinecoercionandcheck('$[0]');",
    "sections": {
        "NAME": {
            "content": "Specio::Constraint::Simple - Class for simple (non-parameterized or specialized) types\n",
            "subsections": []
        },
        "VERSION": {
            "content": "version 0.47\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "my $str = t('Str');\n\nprint $str->name; # Str\n\nmy $parent = $str->parent;\n\nif ( $str->valueisvalid($value) ) { ... }\n\n$str->validateordie($value);\n\nmy $code = $str->inlinecoercionandcheck('$[0]');\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This class implements simple type constraints, constraints without special properties or\nparameterization.\n\nIt does not actually contain any real code of its own. The entire implementation is provided by\nthe Specio::Constraint::Role::Interface role, but the primary API for type constraints is\ndocumented here.\n\nAll other type constraint classes in this distribution implement this API, except where\notherwise noted.\n",
            "subsections": []
        },
        "API": {
            "content": "This class provides the following methods.\n\nSpecio::Constraint::Simple->new(...)\nThis creates a new constraint. It accepts the following named parameters:\n\n*   name => $name\n\nThis is the type's name. The name is optional, but if provided it must be a string.\n\n*   parent => $type\n\nThe type's parent type. This must be an object which does the\nSpecio::Constraint::Role::Interface role.\n\nThis parameter is optional.\n\n*   constraint => sub { ... }\n\nA subroutine reference implementing the constraint. It will be called as a method on the\nobject and passed a single argument, the value to check.\n\nIt should return true or false to indicate whether the value matches the constraint.\n\nThis parameter is mutually exclusive with \"inlinegenerator\".\n\nYou can also pass this option with the key \"where\" in the parameter list.\n\n*   inlinegenerator => sub { ... }\n\nThis should be a subroutine reference which returns a string containing a single term. This\ncode should *not* end in a semicolon. This code should implement the constraint.\n\nThe generator will be called as a method on the constraint with a single argument. That\nargument is the name of the variable being coerced, something like '$[0]' or '$var'.\n\nThe inline generator is expected to include code to implement both the current type and all\nits parents. Typically, the easiest way to do this is to write a subroutine something like\nthis:\n\nsub {\nmy $self = shift;\nmy $var  = shift;\n\nreturn $[0]->parent->inlinecheck( $[1] )\n. ' and more checking code goes here';\n}\n\nThis parameter is mutually exclusive with \"constraint\".\n\nYou can also pass this option with the key \"inline\" in the parameter list.\n\n*   inlineenvironment => {}\n\nThis should be a hash reference of variable names (with sigils) and values for that\nvariable. The values should be *references* to the values of the variables.\n\nThis environment will be used when compiling the constraint as part of a subroutine. The\nnamed variables will be captured as closures in the generated subroutine, using\nEval::Closure.\n\nIt should be very rare to need to set this in the constructor. It's more likely that a\nspecial type subclass would need to provide values that it generates internally.\n\nIf you do set this, you are responsible for generating variable names that won't clash with\nanything else in the inlined code.\n\nThis parameter defaults to an empty hash reference.\n\n*   messagegenerator => sub { ... }\n\nA subroutine to generate an error message when the type check fails. The default message\nsays something like \"Validation failed for type named Int declared in package\nSpecio::Library::Builtins (.../Specio/blib/lib/Specio/Library/Builtins.pm) at line 147 in\nsub named (eval) with value 1.1\".\n\nYou can override this to provide something more specific about the way the type failed.\n\nThe subroutine you provide will be called as a subroutine, *not as a method*, with two\narguments. The first is the description of the type (the bit in the message above that\nstarts with \"type named Int ...\" and ends with \"... in sub named (eval)\". This description\nsays what the thing is and where it was defined.\n\nThe second argument is the value that failed the type check, after any coercions that might\nhave been applied.\n\nYou can also pass this option with the key \"message\" in the parameter list.\n\n*   declaredat => $declaredat\n\nThis parameter must be a Specio::DeclaredAt object.\n\nThis parameter is required.\n\nIt is possible to create a type without a constraint of its own.\n\n$type->name\nReturns the name of the type as it was passed the constructor.\n\n$type->parent\nReturns the parent type passed to the constructor. If the type has no parent this returns\n\"undef\".\n\n$type->isanon\nReturns false for named types, true otherwise.\n\n$type->isatypeof($othertype)\nGiven a type object, this returns true if the type this method is called on is a descendant of\nthat type or is that type.\n\n$type->issametypeas($othertype)\nGiven a type object, this returns true if the type this method is called on is the same as that\ntype.\n\n$type->coercions\nReturns a list of Specio::Coercion objects which belong to this constraint.\n\n$type->coercionfromtype($name)\nGiven a type name, this method returns a Specio::Coercion object which coerces from that type,\nif such a coercion exists.\n\n$type->validateordie($value)\nThis method does nothing if the value is valid. If it is not, it throws a Specio::Exception.\n\n$type->valueisvalid($value)\nReturns true or false depending on whether the $value passes the type constraint.\n\n$type->hasrealconstraint\nThis returns true if the type was created with a \"constraint\" or \"inlinegenerator\" parameter.\nThis is used internally to skip type checks for types that don't actually implement a\nconstraint.\n\n$type->description\nThis returns a string describing the type. This includes the type's name and where it was\ndeclared, so you end up with something like \"'type named Foo declared in package My::Lib\n(lib/My/Lib.pm) at line 42'\". If the type is anonymous the name will be \"anonymous type\".\n\n$type->id\nThis is a unique id for the type as a string. This is useful if you need to make a hash key\nbased on a type, for example. This should be treated as an essentially arbitrary and opaque\nstring, and could change at any time in the future. If you want something human-readable, use\nthe \"$type->description\" method.\n\n$type->addcoercion($coercion)\nThis adds a new Specio::Coercion to the type. If the type already has a coercion from the same\ntype as the new coercion, it will throw an error.\n\n$type->hascoercionfromtype($othertype)\nThis method returns true if the type can coerce from the other type.\n\n$type->coercevalue($value)\nThis attempts to coerce a value into a new value that matches the type. It checks all of the\ntype's coercions. If it finds one which has a \"from\" type that accepts the value, it runs the\ncoercion and returns the new value.\n\nIf it cannot find a matching coercion it returns the original value.\n\n$type->inlinecoercionandcheck($var)\nGiven a variable name, this returns a string of code and an environment hash that implements all\nof the type's coercions as well as the type check itself.\n\nThis will throw an exception unless both the type and all of its coercions are inlinable.\n\nThe generated code will throw a Specio::Exception if the type constraint fails. If the\nconstraint passes, then the generated code returns the (possibly coerced) value.\n\nThe return value is a two-element list. The first element is the code. The second is a hash\nreference containing variables which need to be in scope for the code to work. This is intended\nto be passed to Eval::Closure's \"evalclosure\" subroutine.\n\nThe returned code is a single \"do { }\" block without a terminating semicolon.\n\n$type->inlineassert($var)\nGiven a variable name, this generates code that implements the constraint and throws an\nexception if the variable does not pass the constraint.\n\nThe return value is a two-element list. The first element is the code. The second is a hash\nreference containing variables which need to be in scope for the code to work. This is intended\nto be passed to Eval::Closure's \"evalclosure\" subroutine.\n\n$type->inlinecheck($var)\nGiven a variable name, this returns a string of code that implements the constraint. If the type\nis not inlinable, this method throws an error.\n\n$type->inlinecoercion($var)\nGiven a variable name, this returns a string of code and an environment hash that implements all\nof the type's coercions. *It does not check that the resulting value is valid.*\n\nThis will throw an exception unless all of the type's coercions are inlinable.\n\nThe return value is a two-element list. The first element is the code. The second is a hash\nreference containing variables which need to be in scope for the code to work. This is intended\nto be passed to Eval::Closure's \"evalclosure\" subroutine.\n\nThe returned code is a single \"do { }\" block without a terminating semicolon.\n\n$type->inlineenvironment()\nThis returns a hash defining the variables that need to be closed over when inlining the type.\nThe keys are full variable names like '$foo' or '@bar'. The values are *references* to a\nvariable of the matching type.\n\n$type->coercionsub\nThis method returns a sub ref that takes a single argument and applied all relevant coercions to\nit. This sub ref will use Sub::Quote if all the type's coercions are inlinable.\n\nThis method exists primarily for the benefit of Moo.\n",
            "subsections": []
        },
        "OVERLOADING": {
            "content": "All constraints implement the following overloads:\n",
            "subsections": [
                {
                    "name": "Subroutine De-referencing",
                    "content": "This is done for the benefit of Moo. The returned subroutine uses Sub::Quote if the type\nconstraint is inlinable.\n"
                },
                {
                    "name": "Stringification",
                    "content": "For non-anonymous types, this will be the type's name. For anonymous types, a string like\n\"ANON(Str)\" is generated. However, this string should not be expected to be stable across\nreleases, so don't use it for things like equality checks!\n"
                },
                {
                    "name": "Boolification",
                    "content": "This always returns true.\n\nString Equality (eq)\nThis calls \"$type->issametypeas($other)\" to compare the two types.\n"
                }
            ]
        },
        "ROLES": {
            "content": "This role does the Specio::Constraint::Role::Interface and Specio::Role::Inlinable roles.\n",
            "subsections": []
        },
        "SUPPORT": {
            "content": "Bugs may be submitted at <https://github.com/houseabsolute/Specio/issues>.\n\nI am also usually active on IRC as 'autarch' on \"irc://irc.perl.org\".\n",
            "subsections": []
        },
        "SOURCE": {
            "content": "The source code repository for Specio can be found at <https://github.com/houseabsolute/Specio>.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Dave Rolsky <autarch@urth.org>\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "This software is Copyright (c) 2012 - 2021 by Dave Rolsky.\n\nThis is free software, licensed under:\n\nThe Artistic License 2.0 (GPL Compatible)\n\nThe full text of the license can be found in the LICENSE file included with this distribution.\n",
            "subsections": []
        }
    },
    "summary": "Specio::Constraint::Simple - Class for simple (non-parameterized or specialized) types",
    "flags": [],
    "examples": [],
    "see_also": []
}