{
    "mode": "perldoc",
    "parameter": "Specio::Declare",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Specio%3A%3ADeclare/json",
    "generated": "2026-06-12T19:57:12Z",
    "synopsis": "package MyApp::Type::Library;\nuse parent 'Specio::Exporter';\nuse Specio::Declare;\nuse Specio::Library::Builtins;\ndeclare(\n'Foo',\nparent => t('Str'),\nwhere  => sub { $[0] =~ /foo/i },\n);\ndeclare(\n'ArrayRefOfInt',\nparent => t( 'ArrayRef', of => t('Int') ),\n);\nmy $even = anon(\nparent => t('Int'),\ninline => sub {\nmy $type      = shift;\nmy $valuevar = shift;\nreturn $valuevar . ' % 2 == 0';\n},\n);\ncoerce(\nt('ArrayRef'),\nfrom  => t('Foo'),\nusing => sub { [ $[0] ] },\n);\ncoerce(\n$even,\nfrom  => t('Int'),\nusing => sub { $[0] % 2 ? $[0] + 1 : $[0] },\n);\n# Specio name is DateTime\nanyisatype('DateTime');\n# Specio name is DateTimeObject\nobjectisatype( 'DateTimeObject', class => 'DateTime' );\nanycantype(\n'Duck',\nmethods => [ 'duckwalk', 'quack' ],\n);\nobjectcantype(\n'DuckObject',\nmethods => [ 'duckwalk', 'quack' ],\n);\nenum(\n'Colors',\nvalues => [qw( blue green red )],\n);\nintersection(\n'HashRefAndArrayRef',\nof => [ t('HashRef'), t('ArrayRef') ],\n);\nunion(\n'IntOrArrayRef',\nof => [ t('Int'), t('ArrayRef') ],\n);",
    "sections": {
        "NAME": {
            "content": "Specio::Declare - Specio declaration subroutines\n",
            "subsections": []
        },
        "VERSION": {
            "content": "version 0.47\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "package MyApp::Type::Library;\n\nuse parent 'Specio::Exporter';\n\nuse Specio::Declare;\nuse Specio::Library::Builtins;\n\ndeclare(\n'Foo',\nparent => t('Str'),\nwhere  => sub { $[0] =~ /foo/i },\n);\n\ndeclare(\n'ArrayRefOfInt',\nparent => t( 'ArrayRef', of => t('Int') ),\n);\n\nmy $even = anon(\nparent => t('Int'),\ninline => sub {\nmy $type      = shift;\nmy $valuevar = shift;\n\nreturn $valuevar . ' % 2 == 0';\n},\n);\n\ncoerce(\nt('ArrayRef'),\nfrom  => t('Foo'),\nusing => sub { [ $[0] ] },\n);\n\ncoerce(\n$even,\nfrom  => t('Int'),\nusing => sub { $[0] % 2 ? $[0] + 1 : $[0] },\n);\n\n# Specio name is DateTime\nanyisatype('DateTime');\n\n# Specio name is DateTimeObject\nobjectisatype( 'DateTimeObject', class => 'DateTime' );\n\nanycantype(\n'Duck',\nmethods => [ 'duckwalk', 'quack' ],\n);\n\nobjectcantype(\n'DuckObject',\nmethods => [ 'duckwalk', 'quack' ],\n);\n\nenum(\n'Colors',\nvalues => [qw( blue green red )],\n);\n\nintersection(\n'HashRefAndArrayRef',\nof => [ t('HashRef'), t('ArrayRef') ],\n);\n\nunion(\n'IntOrArrayRef',\nof => [ t('Int'), t('ArrayRef') ],\n);\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This package exports a set of type declaration helpers. Importing this package also causes it to\ncreate a \"t\" subroutine the caller.\n",
            "subsections": []
        },
        "SUBROUTINES": {
            "content": "This module exports the following subroutines.\n\nt('name')\nThis subroutine lets you access any types you have declared so far, as well as any types you\nimported from another type library.\n\nIf you pass an unknown name, it throws an exception.\n\ndeclare(...)\nThis subroutine declares a named type. The first argument is the type name, followed by a set of\nkey/value parameters:\n\n*   parent => $type\n\nThe parent should be another type object. Specifically, it can be anything which does the\nSpecio::Constraint::Role::Interface role. The parent can be a named or anonymous type.\n\n*   where => sub { ... }\n\nThis is a subroutine which defines the type constraint. It will be passed a single argument,\nthe value to check, and it should return true or false to indicate whether or not the value\nis valid for the type.\n\nThis parameter is mutually exclusive with the \"inline\" parameter.\n\n*   inline => sub { ... }\n\nThis is a subroutine that is called to generate inline code to validate the type. Inlining\ncan be *much* faster than simply providing a subroutine with the \"where\" parameter, but is\noften more complicated to get right.\n\nThe inline generator is called as a method on the type with one argument. This argument is a\n*string* containing the variable name to use in the generated code. Typically this is\nsomething like '$[0]' or '$value'.\n\nThe inline generator subroutine should return a *string* of code representing a single term,\nand it *should not* be terminated with a semicolon. This allows the inlined code to be\nsafely included in an \"if\" statement, for example. You can use \"do { }\" blocks and ternaries\nto get everything into one term. Do not assign to the variable you are testing. This single\nterm should evaluate to true or false.\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 $self->parent->inlinecheck($var)\n. ' and more checking code goes here';\n}\n\nOr, more concisely:\n\nsub { $[0]->parent->inlinecheck( $[1] ) . 'more code that checks $[1]' }\n\nThe \"inline\" parameter is mutually exclusive with the \"where\" parameter.\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 method on the type with two arguments. The\nfirst is the description of the type (the bit in the message above that starts with \"type\nnamed Int ...\" and ends with \"... in sub named (eval)\". This description says what the thing\nis 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\nanon(...)\nThis subroutine declares an anonymous type. It is identical to \"declare\" except that it expects\na list of key/value parameters without a type name as the first parameter.\n\ncoerce(...)\nThis declares a coercion from one type to another. The first argument should be an object which\ndoes the Specio::Constraint::Role::Interface role. This can be either a named or anonymous type.\nThis type is the type that the coercion is *to*.\n\nThe remaining arguments are key/value parameters:\n\n*   from => $type\n\nThis must be an object which does the Specio::Constraint::Role::Interface role. This is type\nthat we are coercing *from*. Again, this can be either a named or anonymous type.\n\n*   using => sub { ... }\n\nThis is a subroutine which defines the type coercion. It will be passed a single argument,\nthe value to coerce. It should return a new value of the type this coercion is to.\n\nThis parameter is mutually exclusive with the \"inline\" parameter.\n\n*   inline => sub { ... }\n\nThis is a subroutine that is called to generate inline code to perform the coercion.\n\nThe inline generator is called as a method on the type with one argument. This argument is a\n*string* containing the variable name to use in the generated code. Typically this is\nsomething like '$[0]' or '$value'.\n\nThe inline generator subroutine should return a *string* of code representing a single term,\nand it *should not* be terminated with a semicolon. This allows the inlined code to be\nsafely included in an \"if\" statement, for example. You can use \"do { }\" blocks and ternaries\nto get everything into one term. This single term should evaluate to the new value.\n",
            "subsections": []
        },
        "DECLARATION HELPERS": {
            "content": "This module also exports some helper subs for declaring certain kinds of types:\n\nanyisatype, objectisatype\nThe \"anyisatype\" helper creates a type which accepts a class name or object of the given\nclass. The \"objectisatype\" helper creates a type which only accepts an object of the given\nclass.\n\nThese subroutines take a type name as the first argument. The remaining arguments are key/value\npairs. Currently this is just the \"class\" key, which should be a class name. This is the class\nthat the type requires.\n\nThe type name argument can be omitted to create an anonymous type.\n\nYou can also pass just a single argument, in which case that will be used as both the type's\nname and the class for the constraint to check.\n\nanydoestype, objectdoestype\nThe \"anydoestype\" helper creates a type which accepts a class name or object which does the\ngiven role. The \"objectdoestype\" helper creates a type which only accepts an object which does\nthe given role.\n\nThese subroutines take a type name as the first argument. The remaining arguments are key/value\npairs. Currently this is just the \"role\" key, which should be a role name. This is the class\nthat the type requires.\n\nThis should just work (I hope) with roles created by Moose, Mouse, and Moo (using Role::Tiny).\n\nThe type name argument can be omitted to create an anonymous type.\n\nYou can also pass just a single argument, in which case that will be used as both the type's\nname and the role for the constraint to check.\n\nanycantype, objectcantype\nThe \"anycantype\" helper creates a type which accepts a class name or object with the given\nmethods. The \"objectcantype\" helper creates a type which only accepts an object with the given\nmethods.\n\nThese subroutines take a type name as the first argument. The remaining arguments are key/value\npairs. Currently this is just the \"methods\" key, which can be either a string or array reference\nof strings. These strings are the required methods for the type.\n\nThe type name argument can be omitted to create an anonymous type.\n\nenum\nThis creates a type which accepts a string matching a given list of acceptable values.\n\nThe first argument is the type name. The remaining arguments are key/value pairs. Currently this\nis just the \"values\" key. This should an array reference of acceptable string values.\n\nThe type name argument can be omitted to create an anonymous type.\n\nintersection\nThis creates a type which is the intersection of two or more other types. A union only accepts\nvalues which match all of its underlying types.\n\nThe first argument is the type name. The remaining arguments are key/value pairs. Currently this\nis just the \"of\" key. This should an array reference of types.\n\nThe type name argument can be omitted to create an anonymous type.\n\nunion\nThis creates a type which is the union of two or more other types. A union accepts any of its\nunderlying types.\n\nThe first argument is the type name. The remaining arguments are key/value pairs. Currently this\nis just the \"of\" key. This should an array reference of types.\n\nThe type name argument can be omitted to create an anonymous type.\n",
            "subsections": []
        },
        "PARAMETERIZED TYPES": {
            "content": "You can create a parameterized type by calling \"t\" with additional parameters, like this:\n\nmy $arrayrefofint = t( 'ArrayRef', of => t('Int') );\n\nmy $arrayrefofhashrefofint = t(\n'ArrayRef',\nof => t(\n'HashRef',\nof => t('Int'),\n),\n);\n\nThe \"t\" subroutine assumes that if it receives more than one argument, it should look up the\nnamed type and call \"$type->parameterize(...)\" with the additional arguments.\n\nIf the named type cannot be parameterized, it throws an error.\n\nYou can also call \"$type->parameterize\" directly if needed. See\nSpecio::Constraint::Parameterizable for details.\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::Declare - Specio declaration subroutines",
    "flags": [],
    "examples": [],
    "see_also": []
}