{ "content": [ { "type": "text", "text": "# Specio (man)\n\n## NAME\n\nSpecio - Type constraints and coercions for Perl\n\n## SYNOPSIS\n\npackage MyApp::Type::Library;\nuse Specio::Declare;\nuse Specio::Library::Builtins;\ndeclare(\n'PositiveInt',\nparent => t('Int'),\ninline => sub {\n$[0]->parent->inlinecheck( $[1] )\n. ' && ( '\n. $[1]\n. ' > 0 )';\n},\n);\n# or ...\ndeclare(\n'PositiveInt',\nparent => t('Int'),\nwhere => sub { $[0] > 0 },\n);\ndeclare(\n'ArrayRefOfPositiveInt',\nparent => t(\n'ArrayRef',\nof => t('PositiveInt'),\n),\n);\ncoerce(\n'ArrayRefOfPositiveInt',\nfrom => t('PositiveInt'),\nusing => sub { [ $[0] ] },\n);\nanycantype(\n'Duck',\nmethods => [ 'duckwalk', 'quack' ],\n);\nobjectisatype('MyApp::Person');\n\n## DESCRIPTION\n\nThe \"Specio\" distribution provides classes for representing type constraints and coercion,\nalong with syntax sugar for declaring them.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION** (1 subsections)\n- **BUILTIN TYPES** (1 subsections)\n- **PARAMETERIZABLE TYPES** (1 subsections)\n- **REGISTRIES AND IMPORTING**\n- **CREATING A TYPE LIBRARY**\n- **DECLARING TYPES** (2 subsections)\n- **USING SPECIO WITH OTHER THINGS** (1 subsections)\n- **OPTIONAL PREREQS** (1 subsections)\n- **LONG-TERM PLANS**\n- **SUPPORT**\n- **SOURCE**\n- **DONATIONS**\n- **AUTHOR**\n- **CONTRIBUTORS**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Specio", "section": "", "mode": "man", "summary": "Specio - Type constraints and coercions for Perl", "synopsis": "package MyApp::Type::Library;\nuse Specio::Declare;\nuse Specio::Library::Builtins;\ndeclare(\n'PositiveInt',\nparent => t('Int'),\ninline => sub {\n$[0]->parent->inlinecheck( $[1] )\n. ' && ( '\n. $[1]\n. ' > 0 )';\n},\n);\n# or ...\ndeclare(\n'PositiveInt',\nparent => t('Int'),\nwhere => sub { $[0] > 0 },\n);\ndeclare(\n'ArrayRefOfPositiveInt',\nparent => t(\n'ArrayRef',\nof => t('PositiveInt'),\n),\n);\ncoerce(\n'ArrayRefOfPositiveInt',\nfrom => t('PositiveInt'),\nusing => sub { [ $[0] ] },\n);\nanycantype(\n'Duck',\nmethods => [ 'duckwalk', 'quack' ],\n);\nobjectisatype('MyApp::Person');", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 45, "subsections": [] }, { "name": "DESCRIPTION", "lines": 12, "subsections": [ { "name": "WHAT IS A TYPE?", "lines": 21 } ] }, { "name": "BUILTIN TYPES", "lines": 42, "subsections": [ { "name": "Overloading", "lines": 29 } ] }, { "name": "PARAMETERIZABLE TYPES", "lines": 8, "subsections": [ { "name": "Maybe", "lines": 8 } ] }, { "name": "REGISTRIES AND IMPORTING", "lines": 20, "subsections": [] }, { "name": "CREATING A TYPE LIBRARY", "lines": 34, "subsections": [] }, { "name": "DECLARING TYPES", "lines": 3, "subsections": [ { "name": "USING SPECIO WITH Moose", "lines": 2 }, { "name": "USING SPECIO WITH Moo", "lines": 35 } ] }, { "name": "USING SPECIO WITH OTHER THINGS", "lines": 2, "subsections": [ { "name": "Moose, MooseX::Types, and Specio", "lines": 59 } ] }, { "name": "OPTIONAL PREREQS", "lines": 17, "subsections": [ { "name": "WHY THE NAME?", "lines": 4 } ] }, { "name": "LONG-TERM PLANS", "lines": 3, "subsections": [] }, { "name": "SUPPORT", "lines": 4, "subsections": [] }, { "name": "SOURCE", "lines": 3, "subsections": [] }, { "name": "DONATIONS", "lines": 15, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "CONTRIBUTORS", "lines": 8, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 12, "subsections": [] } ], "sections": { "NAME": { "content": "Specio - Type constraints and coercions for Perl\n", "subsections": [] }, "VERSION": { "content": "version 0.47\n", "subsections": [] }, "SYNOPSIS": { "content": "package MyApp::Type::Library;\n\nuse Specio::Declare;\nuse Specio::Library::Builtins;\n\ndeclare(\n'PositiveInt',\nparent => t('Int'),\ninline => sub {\n$[0]->parent->inlinecheck( $[1] )\n. ' && ( '\n. $[1]\n. ' > 0 )';\n},\n);\n\n# or ...\n\ndeclare(\n'PositiveInt',\nparent => t('Int'),\nwhere => sub { $[0] > 0 },\n);\n\ndeclare(\n'ArrayRefOfPositiveInt',\nparent => t(\n'ArrayRef',\nof => t('PositiveInt'),\n),\n);\n\ncoerce(\n'ArrayRefOfPositiveInt',\nfrom => t('PositiveInt'),\nusing => sub { [ $[0] ] },\n);\n\nanycantype(\n'Duck',\nmethods => [ 'duckwalk', 'quack' ],\n);\n\nobjectisatype('MyApp::Person');\n", "subsections": [] }, "DESCRIPTION": { "content": "The \"Specio\" distribution provides classes for representing type constraints and coercion,\nalong with syntax sugar for declaring them.\n\nNote that this is not a proper type system for Perl. Nothing in this distribution will\nmagically make the Perl interpreter start checking a value's type on assignment to a\nvariable. In fact, there's no built-in way to apply a type to a variable at all.\n\nInstead, you can explicitly check a value against a type, and optionally coerce values to\nthat type.\n\nMy long-term goal is to replace Moose's built-in types and MooseX::Types with this module.\n", "subsections": [ { "name": "WHAT IS A TYPE?", "content": "At it's core, a type is simply a constraint. A constraint is code that checks a value and\nreturns true or false. Most constraints are represented by Specio::Constraint::Simple\nobjects. However, there are other type constraint classes for specialized kinds of\nconstraints.\n\nTypes can be named or anonymous, and each type can have a parent type. A type's constraint is\noptional because sometimes you may want to create a named subtype of some existing type\nwithout adding additional constraints.\n\nConstraints can be expressed either in terms of a simple subroutine reference or in terms of\nan inline generator subroutine reference. The former is easier to write but the latter is\npreferred because it allow for better optimization.\n\nA type can also have an optional message generator subroutine reference. You can use this to\nprovide a more intelligent error message when a value does not pass the constraint, though\nthe default message should suffice for most cases.\n\nFinally, you can associate a set of coercions with a type. A coercion is a subroutine\nreference (or inline generator, like constraints), that takes a value of one type and turns\nit into a value that matches the type the coercion belongs to.\n" } ] }, "BUILTIN TYPES": { "content": "This distribution ships with a set of builtin types representing the types provided by the\nPerl interpreter itself. They are arranged in a hierarchy as follows:\n\nItem\nBool\nMaybe (of `a)\nUndef\nDefined\nValue\nStr\nNum\nInt\nClassName\nRef\nScalarRef (of `a)\nArrayRef (of `a)\nHashRef (of `a)\nCodeRef\nRegexpRef\nGlobRef\nFileHandle\nObject\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. Specifically, they do not\nallow any sort of space in the number, nor do they accept \"Nan\", \"Inf\", or \"Infinity\".\n\nThe \"ClassName\" type constraint checks that the name is valid and that the class is loaded.\n\nThe \"FileHandle\" type accepts either a glob, a scalar filehandle, or anything that isa\nIO::Handle.\n\nAll types accept overloaded objects that support the required operation. See below for\ndetails.\n", "subsections": [ { "name": "Overloading", "content": "Perl'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 make sense.\n\nFor types where overloading makes sense, we explicitly check that the object provides the\ntype overloading we expect. We do not simply try to use the object as the type in question\nand hope it works. This means that these checks effectively ignore the \"fallback\" setting for\nthe overloaded object. In other words, an object that overloads stringification will not pass\nthe \"Bool\" type check unless it also overloads boolification.\n\nMost types do not check that the overloaded method actually returns something that matches\nthe 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{\"\"}\") overloading.\n\nThe \"Num\" type accepts an object that implements numeric (\"'0+'}\") overloading. The \"Int\"\ntype does as well, but it will check that the overloading returns an actual integer.\n\nThe \"ClassName\" type will accept an object with string overloading that returns a class name.\n\nTo make this all more confusing, the \"Value\" type will never accept an object, even though\nsome of its subtypes will.\n\nThe various reference types all accept objects which provide the appropriate overloading. The\n\"FileHandle\" type accepts an object which overloads globification as long as the returned\nglob is an open filehandle.\n" } ] }, "PARAMETERIZABLE TYPES": { "content": "Any type followed by a type parameter \"of `a\" in the hierarchy above can be parameterized.\nThe parameter is itself a type, so you can say you want an \"ArrayRef of Int\", or even an\n\"ArrayRef of HashRef of ScalarRef of ClassName\".\n\nWhen they are parameterized, the \"ScalarRef\" and \"ArrayRef\" types check that the value(s)\nthey refer to match the type parameter. For the \"HashRef\" type, the parameter applies to the\nvalues (keys are never checked).\n", "subsections": [ { "name": "Maybe", "content": "The \"Maybe\" type is a special parameterized type. It allows for either \"undef\" or a value.\nAll by itself, it is meaningless, since it is equivalent to \"Maybe of Item\", which is\nequivalent to Item. When parameterized, it accepts either an \"undef\" or the type of its\nparameter.\n\nThis is useful for optional attributes or parameters. However, you're probably better off\nmaking your code simply not pass the parameter at all This usually makes for a simpler API.\n" } ] }, "REGISTRIES AND IMPORTING": { "content": "Types are local to each package where they are used. When you \"import\" types from some other\nlibrary, 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\" in another\npackage. This has potential for confusion, but it also avoids the magic action at a distance\npollution that comes with a global type naming system.\n\nThe registry is managed internally by the Specio distribution's modules, and is not exposed\nto 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 type. Your\ncoercion from \"Str\" to \"Int\" will not be seen by any other package, unless that package\nexplicitly imports your \"Int\" type.\n\nWhen you import types, you import every type defined in the package you import from. However,\nyou can overwrite an imported type with your own type definition. You cannot define the same\ntype twice internally.\n", "subsections": [] }, "CREATING A TYPE LIBRARY": { "content": "By default, all types created inside a package are invisible to other packages. If you want\nto create a type library, you need to inherit from Specio::Exporter package:\n\npackage 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\nNow the MyApp::Type::Library package will export a single type named \"Foo\". It does not re-\nexport the types provided by Specio::Library::Builtins.\n\nIf you want to make your library re-export some other libraries types, you can ask for this\nexplicitly:\n\npackage MyApp::Type::Library;\n\nuse parent 'Specio::Exporter';\n\nuse Specio::Declare;\nuse Specio::Library::Builtins -reexport;\n\ndeclare( 'Foo, ... );\n\nNow MyApp::Types::Library exports any types it defines, as well as all the types defined in\nSpecio::Library::Builtins.\n", "subsections": [] }, "DECLARING TYPES": { "content": "Use the Specio::Declare module to declare types. It exports a set of helpers for declaring\ntypes. See that module's documentation for more details on these helpers.\n", "subsections": [ { "name": "USING SPECIO WITH Moose", "content": "This should just work. Use a Specio type anywhere you'd specify a type.\n" }, { "name": "USING SPECIO WITH Moo", "content": "Using Specio with Moo is easy. You can pass Specio constraint objects as \"isa\" parameters for\nattributes. For coercions, simply call \"$type->coercionsub\".\n\npackage Foo;\n\nuse Specio::Declare;\nuse Specio::Library::Builtins;\nuse Moo;\n\nmy $strtype = t('Str');\nhas string => (\nis => 'ro',\nisa => $strtype,\n);\n\nmy $ucstr = declare(\n'UCStr',\nparent => t('Str'),\nwhere => sub { $[0] =~ /^[A-Z]+$/ },\n);\n\ncoerce(\n$ucstr,\nfrom => t('Str'),\nusing => sub { return uc $[0] },\n);\n\nhas ucstr => (\nis => 'ro',\nisa => $ucstr,\ncoerce => $ucstr->coercionsub,\n);\n\nThe subs returned by Specio use Sub::Quote internally and are suitable for inlining.\n" } ] }, "USING SPECIO WITH OTHER THINGS": { "content": "See Specio::Constraint::Simple for the API that all constraint objects share.\n", "subsections": [ { "name": "Moose, MooseX::Types, and Specio", "content": "This module aims to supplant both Moose's built-in type system (see\nMoose::Util::TypeConstraints aka MUTC) and MooseX::Types, which attempts to patch some of the\nholes 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\nUnlike Moose and MooseX::Types, type names are always local to the current package. There\nis no possibility of name collision between different modules, so you can safely use\nshort type names.\n\nUnlike MooseX::Types, types are strings, so there is no possibility of colliding with\nexisting class or subroutine names.\n\n• No type auto-creation\n\nTypes are always retrieved using the \"t()\" subroutine. If you pass an unknown name to\nthis subroutine it dies. This is different from Moose and MooseX::Types, which assume\nthat unknown names are class names.\n\n• Anon types are explicit\n\nWith Moose and MooseX::Types, you use the same subroutine, \"subtype()\", to declare both\nnamed and anonymous types. With Specio, you use \"declare()\" for named types and \"anon()\"\nfor anonymous types.\n\n• Class and object types are separate\n\nMoose and MooseX::Types have \"classtype\" and \"ducktype\". The former type requires an\nobject, while the latter accepts a class name or object.\n\nWith Specio, the distinction between accepting an object versus object or class is\nexplicit. There are six declaration helpers, \"objectcantype\", \"objectdoestype\",\n\"objectisatype\", \"anycantype\", \"anydoestype\", and \"anyisatype\".\n\n• Overloading support is baked in\n\nPerl's overloading is quite broken but ignoring it makes Moose's type system frustrating\nto use in many cases.\n\n• Types can either have a constraint or inline generator, not both\n\nMoose and MooseX::Types types can be defined with a subroutine reference as the\nconstraint, an inline generator subroutine, or both. This is purely for backwards\ncompatibility, and it makes the internals more complicated than they need to be.\n\nWith Specio, a constraint can have either a subroutine reference or an inline generator,\nnot both.\n\n• Coercions can be inlined\n\nI simply never got around to implementing this in Moose.\n\n• No crazy coercion features\n\nMoose has some bizarre (and mostly) undocumented features relating to coercions and\nparameterizable types. This is a misfeature.\n" } ] }, "OPTIONAL PREREQS": { "content": "There are several optional prereqs that if installed will make this distribution better in\nsome way.\n\n• Ref::Util\n\nInstalling this will speed up a number of type checks for built-in types.\n\n• XString\n\nIf this is installed it will be loaded instead of the B module if you have Perl 5.10 or\ngreater. This module is much more memory efficient than loading all of B.\n\n• Sub::Util or Sub::Name\n\nIf one of these is installed then stack traces that end up in Specio code will have much\nbetter subroutine names for any frames.\n", "subsections": [ { "name": "WHY THE NAME?", "content": "This distro was originally called \"Type\", but that's an awfully generic top level namespace.\nSpecio is Latin for for \"look at\" and \"spec\" is the root for the word \"species\". It's short,\nrelatively easy to type, and not used by any other distro.\n" } ] }, "LONG-TERM PLANS": { "content": "Eventually I'd like to see this distro replace Moose's internal type system, which would also\nmake MooseX::Types obsolete.\n", "subsections": [] }, "SUPPORT": { "content": "Bugs may be submitted at .\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\n.\n", "subsections": [] }, "DONATIONS": { "content": "If you'd like to thank me for the work I've done on this module, please consider making a\n\"donation\" to me via PayPal. I spend a lot of free time creating free software, and would\nappreciate any support you'd care to offer.\n\nPlease note that I am not suggesting that you must do this in order for me to continue\nworking on this particular software. I will continue to do so, inasmuch as I have in the\npast, for as long as it interests me.\n\nSimilarly, a donation made in this way will probably not make me work on this software much\nmore, unless I get so many donations that I can consider working on free software full time\n(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 button at\n.\n", "subsections": [] }, "AUTHOR": { "content": "Dave Rolsky \n", "subsections": [] }, "CONTRIBUTORS": { "content": "• Chris White \n\n• cpansprout \n\n• Graham Knop \n\n• Karen Etheridge \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\ndistribution.\n\n\n\nperl v5.32.0 2021-01-31 Specio(3pm)", "subsections": [] } } } }