{"id":15478428,"url":"https://github.com/houseabsolute/specio","last_synced_at":"2025-08-30T02:11:44.208Z","repository":{"id":8861799,"uuid":"10572849","full_name":"houseabsolute/Specio","owner":"houseabsolute","description":"Type constraints and coercions for Perl","archived":false,"fork":false,"pushed_at":"2025-08-09T14:40:11.000Z","size":1162,"stargazers_count":4,"open_issues_count":5,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-09T16:27:10.190Z","etag":null,"topics":["moose","perl"],"latest_commit_sha":null,"homepage":"https://metacpan.org/release/Specio/","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/houseabsolute.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"autarch"}},"created_at":"2013-06-08T18:56:25.000Z","updated_at":"2025-08-09T14:40:14.000Z","dependencies_parsed_at":"2025-06-19T17:33:38.228Z","dependency_job_id":null,"html_url":"https://github.com/houseabsolute/Specio","commit_stats":null,"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"purl":"pkg:github/houseabsolute/Specio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/houseabsolute%2FSpecio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/houseabsolute%2FSpecio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/houseabsolute%2FSpecio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/houseabsolute%2FSpecio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/houseabsolute","download_url":"https://codeload.github.com/houseabsolute/Specio/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/houseabsolute%2FSpecio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272793050,"owners_count":24993837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["moose","perl"],"created_at":"2024-10-02T04:04:15.226Z","updated_at":"2025-08-30T02:11:44.195Z","avatar_url":"https://github.com/houseabsolute.png","language":"Perl","funding_links":["https://github.com/sponsors/autarch"],"categories":[],"sub_categories":[],"readme":"# NAME\n\nSpecio - Type constraints and coercions for Perl\n\n# VERSION\n\nversion 0.52\n\n# SYNOPSIS\n\n    package MyApp::Type::Library;\n\n    use Specio::Declare;\n    use Specio::Library::Builtins;\n\n    declare(\n        'PositiveInt',\n        parent =\u003e t('Int'),\n        inline =\u003e sub {\n            $_[0]-\u003eparent-\u003einline_check( $_[1] )\n                . ' \u0026\u0026 ( '\n                . $_[1]\n                . ' \u003e 0 )';\n        },\n    );\n\n    # or ...\n\n    declare(\n        'PositiveInt',\n        parent =\u003e t('Int'),\n        where  =\u003e sub { $_[0] \u003e 0 },\n    );\n\n    declare(\n        'ArrayRefOfPositiveInt',\n        parent =\u003e t(\n            'ArrayRef',\n            of =\u003e t('PositiveInt'),\n        ),\n    );\n\n    coerce(\n        'ArrayRefOfPositiveInt',\n        from  =\u003e t('PositiveInt'),\n        using =\u003e sub { [ $_[0] ] },\n    );\n\n    any_can_type(\n        'Duck',\n        methods =\u003e [ 'duck_walk', 'quack' ],\n    );\n\n    object_isa_type('MyApp::Person');\n\n# DESCRIPTION\n\nThe `Specio` distribution provides classes for representing type constraints\nand coercion, along with syntax sugar for declaring them.\n\nNote that this is not a proper type system for Perl. Nothing in this\ndistribution will magically make the Perl interpreter start checking a value's\ntype on assignment to a variable. In fact, there's no built-in way to apply a\ntype to a variable at all.\n\nInstead, you can explicitly check a value against a type, and optionally coerce\nvalues to that type.\n\n# WHAT IS A TYPE?\n\nAt it's core, a type is simply a constraint. A constraint is code that checks a\nvalue and returns true or false. Most constraints are represented by\n[Specio::Constraint::Simple](https://metacpan.org/pod/Specio%3A%3AConstraint%3A%3ASimple) objects. However, there are other type constraint\nclasses for specialized kinds of constraints.\n\nTypes can be named or anonymous, and each type can have a parent type. A type's\nconstraint is optional because sometimes you may want to create a named subtype\nof some existing type without adding additional constraints.\n\nConstraints can be expressed either in terms of a simple subroutine reference\nor in terms of an inline generator subroutine reference. The former is easier\nto write but the latter is preferred because it allow for better optimization.\n\nA type can also have an optional message generator subroutine reference. You\ncan use this to provide a more intelligent error message when a value does not\npass the constraint, though the default message should suffice for most cases.\n\nFinally, you can associate a set of coercions with a type. A coercion is a\nsubroutine reference (or inline generator, like constraints), that takes a\nvalue of one type and turns it into a value that matches the type the coercion\nbelongs to.\n\n# BUILTIN TYPES\n\nThis distribution ships with a set of builtin types representing the types\nprovided by the Perl interpreter itself. They are arranged in a hierarchy as\nfollows:\n\n    Item\n        Bool\n        Maybe (of `a)\n        Undef\n        Defined\n            Value\n                Str\n                    Num\n                        Int\n                    ClassName\n            Ref\n                ScalarRef (of `a)\n                ArrayRef (of `a)\n                HashRef (of `a)\n                CodeRef\n                RegexpRef\n                GlobRef\n                FileHandle\n                Object\n\nThe `Item` type accepts anything and everything.\n\nThe `Bool` type only accepts `undef`, `0`, or `1`.\n\nThe `Undef` type only accepts `undef`.\n\nThe `Defined` type accepts anything _except_ `undef`.\n\nThe `Num` and `Int` types are stricter about numbers than Perl is.\nSpecifically, they do not allow any sort of space in the number, nor do they\naccept \"Nan\", \"Inf\", or \"Infinity\".\n\nThe `ClassName` type constraint checks that the name is valid _and_ that the\nclass is loaded.\n\nThe `FileHandle` type accepts either a glob, a scalar filehandle, or anything\nthat isa [IO::Handle](https://metacpan.org/pod/IO%3A%3AHandle).\n\nAll types accept overloaded objects that support the required operation. See\nbelow for details.\n\n## Overloading\n\nPerl's overloading is horribly broken and doesn't make much sense at all.\n\nHowever, unlike Moose, all type constraints allow overloaded objects where they\nmake sense.\n\nFor types where overloading makes sense, we explicitly check that the object\nprovides the type overloading we expect. We _do not_ simply try to use the\nobject as the type in question and hope it works. This means that these checks\neffectively ignore the `fallback` setting for the overloaded object. In other\nwords, an object that overloads stringification will not pass the `Bool` type\ncheck unless it _also_ overloads boolification.\n\nMost types do not check that the overloaded method actually returns something\nthat matches the constraint. This may change in the future.\n\nThe `Bool` type accepts an object that implements `bool` overloading.\n\nThe `Str` type accepts an object that implements string (`q{\"\"}`)\noverloading.\n\nThe `Num` type accepts an object that implements numeric (`'0+'}`)\noverloading. The `Int` type does as well, but it will check that the\noverloading returns an actual integer.\n\nThe `ClassName` type will accept an object with string overloading that\nreturns a class name.\n\nTo make this all more confusing, the `Value` type will _never_ accept an\nobject, even though some of its subtypes will.\n\nThe various reference types all accept objects which provide the appropriate\noverloading. The `FileHandle` type accepts an object which overloads\nglobification as long as the returned glob is an open filehandle.\n\n# PARAMETERIZABLE TYPES\n\nAny type followed by a type parameter `` of `a `` in the hierarchy above can be\nparameterized. The parameter is itself a type, so you can say you want an\n\"ArrayRef of Int\", or even an \"ArrayRef of HashRef of ScalarRef of ClassName\".\n\nWhen they are parameterized, the `ScalarRef` and `ArrayRef` types check that\nthe value(s) they refer to match the type parameter. For the `HashRef` type,\nthe parameter applies to the values (keys are never checked).\n\n## Maybe\n\nThe `Maybe` type is a special parameterized type. It allows for either\n`undef` or a value. All by itself, it is meaningless, since it is equivalent\nto \"Maybe of Item\", which is equivalent to Item. When parameterized, it accepts\neither an `undef` or the type of its parameter.\n\nThis is useful for optional attributes or parameters. However, you're probably\nbetter off making your code simply not pass the parameter at all This usually\nmakes for a simpler API.\n\n# REGISTRIES AND IMPORTING\n\nTypes are local to each package where they are used. When you \"import\" types\nfrom some other library, you are actually making a copy of that type.\n\nThis means that a type named \"Foo\" in one package may not be the same as \"Foo\"\nin another package. This has potential for confusion, but it also avoids the\nmagic action at a distance pollution that comes with a global type naming\nsystem.\n\nThe registry is managed internally by the Specio distribution's modules, and is\nnot exposed to your code. To access a type, you always call `t('TypeName')`.\n\nThis returns the named type or dies if no such type exists.\n\nBecause types are always copied on import, it's safe to create coercions on any\ntype. Your coercion from `Str` to `Int` will not be seen by any other\npackage, unless that package explicitly imports your `Int` type.\n\nWhen you import types, you import every type defined in the package you import\nfrom. However, you _can_ overwrite an imported type with your own type\ndefinition. You _cannot_ define the same type twice internally.\n\n# CREATING A TYPE LIBRARY\n\nBy default, all types created inside a package are invisible to other packages.\nIf you want to create a type library, you need to inherit from\n[Specio::Exporter](https://metacpan.org/pod/Specio%3A%3AExporter) package:\n\n    package MyApp::Type::Library;\n\n    use parent 'Specio::Exporter';\n\n    use Specio::Declare;\n    use Specio::Library::Builtins;\n\n    declare(\n        'Foo',\n        parent =\u003e t('Str'),\n        where  =\u003e sub { $_[0] =~ /foo/i },\n    );\n\nNow the MyApp::Type::Library package will export a single type named `Foo`. It\n_does not_ re-export the types provided by [Specio::Library::Builtins](https://metacpan.org/pod/Specio%3A%3ALibrary%3A%3ABuiltins).\n\nIf you want to make your library re-export some other libraries types, you can\nask for this explicitly:\n\n    package MyApp::Type::Library;\n\n    use parent 'Specio::Exporter';\n\n    use Specio::Declare;\n    use Specio::Library::Builtins -reexport;\n\n    declare( 'Foo, ... );\n\nNow MyApp::Types::Library exports any types it defines, as well as all the\ntypes defined in [Specio::Library::Builtins](https://metacpan.org/pod/Specio%3A%3ALibrary%3A%3ABuiltins).\n\n# DECLARING TYPES\n\nUse the [Specio::Declare](https://metacpan.org/pod/Specio%3A%3ADeclare) module to declare types. It exports a set of helpers\nfor declaring types. See that module's documentation for more details on these\nhelpers.\n\n# USING SPECIO WITH [Moose](https://metacpan.org/pod/Moose)\n\nThis should just work. Use a Specio type anywhere you'd specify a type.\n\n# USING SPECIO WITH [Moo](https://metacpan.org/pod/Moo)\n\nUsing Specio with Moo is easy. You can pass Specio constraint objects as `isa`\nparameters for attributes. For coercions, simply call `$type-\u003ecoercion_sub`.\n\n    package Foo;\n\n    use Specio::Declare;\n    use Specio::Library::Builtins;\n    use Moo;\n\n    my $str_type = t('Str');\n    has string =\u003e (\n       is  =\u003e 'ro',\n       isa =\u003e $str_type,\n    );\n\n    my $ucstr = declare(\n        'UCStr',\n        parent =\u003e t('Str'),\n        where  =\u003e sub { $_[0] =~ /^[A-Z]+$/ },\n    );\n\n    coerce(\n        $ucstr,\n        from  =\u003e t('Str'),\n        using =\u003e sub { return uc $_[0] },\n    );\n\n    has ucstr =\u003e (\n        is     =\u003e 'ro',\n        isa    =\u003e $ucstr,\n        coerce =\u003e $ucstr-\u003ecoercion_sub,\n    );\n\nThe subs returned by Specio use [Sub::Quote](https://metacpan.org/pod/Sub%3A%3AQuote) internally and are suitable for\ninlining.\n\n# USING SPECIO WITH OTHER THINGS\n\nSee [Specio::Constraint::Simple](https://metacpan.org/pod/Specio%3A%3AConstraint%3A%3ASimple) for the API that all constraint objects\nshare.\n\n# [Moose](https://metacpan.org/pod/Moose), [MooseX::Types](https://metacpan.org/pod/MooseX%3A%3ATypes), and Specio\n\nThis module aims to supplant both [Moose](https://metacpan.org/pod/Moose)'s built-in type system (see\n[Moose::Util::TypeConstraints](https://metacpan.org/pod/Moose%3A%3AUtil%3A%3ATypeConstraints) aka MUTC) and [MooseX::Types](https://metacpan.org/pod/MooseX%3A%3ATypes), which attempts\nto patch some of the holes in the Moose built-in type design.\n\nHere are some of the salient differences:\n\n- Types names are strings, but they're not global\n\n    Unlike Moose and MooseX::Types, type names are always local to the current\n    package. There is no possibility of name collision between different modules,\n    so you can safely use short type names.\n\n    Unlike MooseX::Types, types are strings, so there is no possibility of\n    colliding with existing class or subroutine names.\n\n- No type auto-creation\n\n    Types are always retrieved using the `t()` subroutine. If you pass an unknown\n    name to this subroutine it dies. This is different from Moose and\n    MooseX::Types, which assume that unknown names are class names.\n\n- Anon types are explicit\n\n    With [Moose](https://metacpan.org/pod/Moose) and [MooseX::Types](https://metacpan.org/pod/MooseX%3A%3ATypes), you use the same subroutine, `subtype()`,\n    to declare both named and anonymous types. With Specio, you use `declare()`\n    for named types and `anon()` for anonymous types.\n\n- Class and object types are separate\n\n    Moose and MooseX::Types have `class_type` and `duck_type`. The former type\n    requires an object, while the latter accepts a class name or object.\n\n    With Specio, the distinction between accepting an object versus object or class\n    is explicit. There are six declaration helpers, `object_can_type`,\n    `object_does_type`, `object_isa_type`, `any_can_type`, `any_does_type`, and\n    `any_isa_type`.\n\n- Overloading support is baked in\n\n    Perl's overloading is quite broken but ignoring it makes Moose's type system\n    frustrating to use in many cases.\n\n- Types can either have a constraint or inline generator, not both\n\n    Moose and MooseX::Types types can be defined with a subroutine reference as the\n    constraint, an inline generator subroutine, or both. This is purely for\n    backwards compatibility, and it makes the internals more complicated than they\n    need to be.\n\n    With Specio, a constraint can have _either_ a subroutine reference or an\n    inline generator, not both.\n\n- Coercions can be inlined\n\n    I simply never got around to implementing this in Moose.\n\n- No crazy coercion features\n\n    Moose has some bizarre (and mostly) undocumented features relating to coercions\n    and parameterizable types. This is a misfeature.\n\n# OPTIONAL PREREQS\n\nThere are several optional prereqs that if installed will make this\ndistribution better in some way.\n\n- [Ref::Util](https://metacpan.org/pod/Ref%3A%3AUtil)\n\n    Installing this will speed up a number of type checks for built-in types.\n\n- [XString](https://metacpan.org/pod/XString)\n\n    If this is installed it will be loaded instead of the [B](https://metacpan.org/pod/B) module if you have\n    Perl 5.10 or greater. This module is much more memory efficient than loading\n    all of [B](https://metacpan.org/pod/B).\n\n- [Sub::Util](https://metacpan.org/pod/Sub%3A%3AUtil) or [Sub::Name](https://metacpan.org/pod/Sub%3A%3AName)\n\n    If one of these is installed then stack traces that end up in Specio code will\n    have much better subroutine names for any frames.\n\n# FORCING PURE PERL MODE\n\nFor some use cases (notably fatpacking a program), you may want to force Specio\nto use pure Perl code instead of XS code. This can be done by setting the\nenvironment variable `SPECIO_IMPLEMENTATION` to `PP`.\n\n# WHY THE NAME?\n\nThis distro was originally called \"Type\", but that's an awfully generic top\nlevel namespace. Specio is Latin for for \"look at\" and \"spec\" is the root for\nthe word \"species\". It's short, relatively easy to type, and not used by any\nother distro.\n\n# SUPPORT\n\nBugs may be submitted at [https://github.com/houseabsolute/Specio/issues](https://github.com/houseabsolute/Specio/issues).\n\n# SOURCE\n\nThe source code repository for Specio can be found at [https://github.com/houseabsolute/Specio](https://github.com/houseabsolute/Specio).\n\n# DONATIONS\n\nIf you'd like to thank me for the work I've done on this module, please\nconsider making a \"donation\" to me via PayPal. I spend a lot of free time\ncreating free software, and would appreciate any support you'd care to offer.\n\nPlease note that **I am not suggesting that you must do this** in order for me\nto continue working on this particular software. I will continue to do so,\ninasmuch as I have in the past, for as long as it interests me.\n\nSimilarly, a donation made in this way will probably not make me work on this\nsoftware much more, unless I get so many donations that I can consider working\non free software full time (let's all have a chuckle at that together).\n\nTo donate, log into PayPal and send money to autarch@urth.org, or use the\nbutton at [https://houseabsolute.com/foss-donations/](https://houseabsolute.com/foss-donations/).\n\n# AUTHOR\n\nDave Rolsky \u003cautarch@urth.org\u003e\n\n# CONTRIBUTORS\n\n- Andrew Rodland \u003candrewr@vimeo.com\u003e\n- Chris White \u003cchrisw@leehayes.com\u003e\n- cpansprout \u003ccpansprout@gmail.com\u003e\n- Graham Knop \u003chaarg@haarg.org\u003e\n- Karen Etheridge \u003cether@cpan.org\u003e\n- Vitaly Lipatov \u003clav@altlinux.ru\u003e\n\n# COPYRIGHT AND LICENSE\n\nThis software is Copyright (c) 2012 - 2025 by Dave Rolsky.\n\nThis is free software, licensed under:\n\n    The Artistic License 2.0 (GPL Compatible)\n\nThe full text of the license can be found in the\n`LICENSE` file included with this distribution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhouseabsolute%2Fspecio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhouseabsolute%2Fspecio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhouseabsolute%2Fspecio/lists"}