{ "content": [ { "type": "text", "text": "# perlclass (man)\n\n## NAME\n\nperlclass - Perl class syntax reference\n\n## SYNOPSIS\n\nuse v5.38;\nuse feature 'class';\nclass My::Example 1.234 {\nfield $x;\nADJUST {\n$x = \"Hello, world\";\n}\nmethod printmessage {\nsay $x;\n}\n}\nMy::Example->new->printmessage;\n\n## DESCRIPTION\n\nThis document describes the syntax of the Perl's \"class\" feature, which provides native\nkeywords supporting object-oriented programming paradigm.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (1 subsections)\n- **KEYWORDS** (3 subsections)\n- **ATTRIBUTES** (3 subsections)\n- **OBJECT LIFECYCLE** (4 subsections)\n- **TODO**\n- **AUTHORS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "perlclass", "section": "", "mode": "man", "summary": "perlclass - Perl class syntax reference", "synopsis": "use v5.38;\nuse feature 'class';\nclass My::Example 1.234 {\nfield $x;\nADJUST {\n$x = \"Hello, world\";\n}\nmethod printmessage {\nsay $x;\n}\n}\nMy::Example->new->printmessage;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 17, "subsections": [] }, { "name": "DESCRIPTION", "lines": 3, "subsections": [ { "name": "History", "lines": 9 } ] }, { "name": "KEYWORDS", "lines": 3, "subsections": [ { "name": "class", "lines": 23 }, { "name": "field", "lines": 38 }, { "name": "method", "lines": 39 } ] }, { "name": "ATTRIBUTES", "lines": 4, "subsections": [ { "name": "Class attributes", "lines": 18 }, { "name": "Field attributes", "lines": 13 }, { "name": "Method attributes", "lines": 2 } ] }, { "name": "OBJECT LIFECYCLE", "lines": 1, "subsections": [ { "name": "Construction", "lines": 8 }, { "name": "Adjustment", "lines": 7 }, { "name": "Lifetime", "lines": 6 }, { "name": "Destruction", "lines": 3 } ] }, { "name": "TODO", "lines": 57, "subsections": [] }, { "name": "AUTHORS", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "perlclass - Perl class syntax reference\n", "subsections": [] }, "SYNOPSIS": { "content": "use v5.38;\nuse feature 'class';\n\nclass My::Example 1.234 {\nfield $x;\n\nADJUST {\n$x = \"Hello, world\";\n}\n\nmethod printmessage {\nsay $x;\n}\n}\n\nMy::Example->new->printmessage;\n", "subsections": [] }, "DESCRIPTION": { "content": "This document describes the syntax of the Perl's \"class\" feature, which provides native\nkeywords supporting object-oriented programming paradigm.\n", "subsections": [ { "name": "History", "content": "Since Perl 5, support for objects revolved around the concept of blessing references with a\npackage name. Such reference could then be used to call subroutines from the package it was\nblessed with (or any of its parents). This system, while bare-bones, was flexible enough to\nallow creation of multiple more advanced, community-driven systems for object orientation.\n\nClass feature is a core implementation of class syntax which is familiar to what one would\nfind in other programming languages. It isn't a \"bless\" wrapper, but a completely new system\nbuilt right into the perl interpreter.\n" } ] }, "KEYWORDS": { "content": "Enabling the \"class\" feature allows the usage of the following new keywords in the scope of\ncurrent package:\n", "subsections": [ { "name": "class", "content": "class NAME BLOCK\n\nclass NAME VERSION BLOCK\n\nclass NAME;\n\nclass NAME VERSION;\n\nThe \"class\" keyword declares a new package which is intended to be a class. All other\nkeywords from the \"class\" feature should be used in scope of this declaration.\n\nclass WithVersion 1.000 {\n# class definition goes here\n}\n\nClasses can be declared in either block or statement syntax. If a block is used, the body of\nthe block contains the implementation of the class. If the statement form is used, the\nremainder of the file is used up until the next \"class\" or \"package\" statement.\n\n\"class\" and \"package\" declarations are similar, but classes automatically get a constructor\nnamed \"new\" - You don't have to (and should not) write one. Additionally, in the class BLOCK\nyou are allowed to declare fields and methods.\n" }, { "name": "field", "content": "field VARIABLENAME;\n\nfield VARIABLENAME = EXPR;\n\nfield VARIABLENAME : ATTRIBUTES;\n\nfield VARIABLENAME : ATTRIBUTES = EXPR;\n\nFields are variables which are visible in the scope of the class - more specifically within\n\"method\" and \"ADJUST\" blocks. Each class instance get their own storage of fields,\nindependent of each other.\n\nA field behaves like a normal lexically scoped variable. It has a sigil and is private to the\nclass (though creation of an accessor method will make it accessible from the outside). The\nmain difference is that different instances access different values in the same scope.\n\nclass WithFields {\nfield $scalar = 42;\nfield @array = qw(this is just an array);\nfield %hash = (species => 'Martian', planet => 'Mars');\n}\n\nFields may optionally have initializing expressions. If present, the expression will be\nevaluated within the constructor of each object instance. During each evaluation, the\nexpression can use the value of any previously-set field, as well as see any other variables\nin scope.\n\nclass WithACounter {\nmy $nextcount = 1;\nfield $count = $nextcount++;\n}\n\nWhen combined with the \":param\" field attribute, the defaulting expression can use any of the\n\"=\", \"//=\" or \"||=\" operators. Expressions using \"=\" will apply whenever the caller did not\npass the corresponding parameter to the constructor at all. Expressions using \"//=\" will also\napply if the caller did pass the parameter but the value was undefined, and expressions using\n\"||=\" will apply if the value was false.\n" }, { "name": "method", "content": "method METHODNAME SIGNATURE BLOCK\n\nmethod METHODNAME BLOCK\n\nmethod SIGNATURE BLOCK\n\nmethod BLOCK\n\nMethods are subroutines intended to be called in the context of class objects.\n\nA variable named $self populated with the current object instance will automatically be\ncreated in the lexical scope of \"method\".\n\nMethods always act as if \"use feature 'signatures'\" is in effect, but $self will not appear\nin the arguments list as far as the signature is concerned.\n\nclass WithMethods {\nfield $greetings;\n\nADJUST {\n$greetings = \"Hello\";\n}\n\nmethod greet($name = \"someone\") {\nsay \"$greetings, $name\";\n}\n}\n\nJust like regular subroutines, methods can be anonymous:\n\nclass AnonMethodFactory {\n\nmethod getanonmethod {\nreturn method {\nreturn 'this is an anonymous method';\n};\n}\n}\n" } ] }, "ATTRIBUTES": { "content": "Specific aspects of the keywords mentioned above are managed using attributes. Attributes all\nstart with a colon, and one or more of them can be appended after the item's name, separated\nby a space.\n", "subsections": [ { "name": "Class attributes", "content": ":isa\n\nClasses may inherit from one superclass, by using the \":isa\" class attribute.\n\nclass Example::Base { ... }\n\nclass Example::Subclass :isa(Example::Base) { ... }\n\nInherited methods are visible and may be invoked. Fields are always lexical and therefore not\nvisible by inheritance.\n\nThe \":isa\" attribute may request a minimum version of the base class; it is applied similar\nto \"use\" - if the provided version is too low it will fail at compile time.\n\nclass Example::Subclass :isa(Example::Base 2.345) { ... }\n\nThe \":isa\" attribute will attempt to \"require\" the named module if it is not already loaded.\n" }, { "name": "Field attributes", "content": ":param\n\nA scalar field with a \":param\" attribute will take its value from a named parameter passed to\nthe constructor. By default the parameter will have the same name as the field (minus its\nleading \"$\" sigil), but a different name can be specified in the attribute.\n\nfield $x :param;\nfield $y :param(theyvalue);\n\nIf there is no defaulting expression then the parameter is required by the constructor; the\ncaller must pass it or an exception is thrown. With a defaulting expression this becomes\noptional.\n" }, { "name": "Method attributes", "content": "None yet.\n" } ] }, "OBJECT LIFECYCLE": { "content": "", "subsections": [ { "name": "Construction", "content": "Each object begins its life with a constructor call. The constructor is always named \"new\"\nand is invoked like a method call on the class name:\n\nmy $object = My::Class->new(%arguments);\n\nDuring the construction, class fields are compared to %arguments hash and populated where\npossible.\n" }, { "name": "Adjustment", "content": "Object adjustment can be performed during the construction to run user-defined code. It is\ndone with the help of \"ADJUST\" blocks, which are called in order of declaration.\n\nThey are similar to \"BEGIN\" blocks, which run during the compilation of a package. However,\nthey also have access to $self lexical (object instance) and all object fields created up to\nthat point.\n" }, { "name": "Lifetime", "content": "After the construction phase, object is ready to be used.\n\nUsing \"blessed\" (\"Scalar::Util::blessed\" or \"builtin::blessed\") on the object will return the\nname of the class, while \"reftype\" (\"Scalar::Util::reftype\" or \"builtin::reftype\") will\nreturn the string 'OBJECT'.\n" }, { "name": "Destruction", "content": "Just like with other references, when object reference count reaches zero it will\nautomatically be destroyed.\n" } ] }, "TODO": { "content": "This feature is still experimental and very incomplete. The following list gives some\noverview of the kinds of work still to be added or changed:\n\n• Roles\n\nSome syntax for declaring a role (likely a \"role\" keyword), and for consuming a role into\na class (likely a :does() attribute).\n\n• Parameters to ADJUST blocks\n\nSome syntax for declaring that an \"ADJUST\" block can consume named parameters, which\nbecome part of the class constructor's API. This might be inspired by a similar plan to\nadd named arguments to subroutine signatures.\n\nclass X {\nADJUST (:$alpha, :$beta = 123) {\n...\n}\n}\n\nmy $obj = X->new(alpha => 456);\n\n• ADJUST blocks as true blocks\n\nCurrently, every ADJUST block is wrapped in its own CV that gets invoked with the full\nENTERSUB overhead. It should be possible to use the same mechanism that makes all field\ninitializer expressions appear within the same CV on ADJUST blocks as well, merging them\nall into a single CV per class. This will make it faster to invoke if a class has more\nthan one of them.\n\n• Accessor generator attributes\n\nAttributes to request that accessor methods be generated for fields. Likely \":reader\" and\n\":writer\".\n\nclass X {\nfield $name :reader;\n}\n\nEquivalent to\n\nclass X {\nfield $name;\nmethod name { return $name; }\n}\n\n• Metaprogramming\n\nAn extension of the metaprogramming API (currently proposed by RFC0022\n) which adds knowledge of classes, methods, fields,\nADJUST blocks, and other such class-related details.\n\n• Extension Customisation\n\nWays in which out-of-core modules can interact with the class system, including an\nability for them to provide new class or field attributes.\n", "subsections": [] }, "AUTHORS": { "content": "Paul Evans\n\nBartosz Jarzyna\n\nperl v5.38.2 2026-06-12 PERLCLASS(1)", "subsections": [] } } } }