{
    "content": [
        {
            "type": "text",
            "text": "# perlpragma (man)\n\n## NAME\n\nperlpragma - how to write a user pragma\n\n## DESCRIPTION\n\nA pragma is a module which influences some aspect of the compile time or run time behaviour\nof Perl, such as \"strict\" or \"warnings\". With Perl 5.10 you are no longer limited to the\nbuilt in pragmata; you can now create user pragmata that modify the behaviour of user\nfunctions within a lexical scope.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION** (3 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "perlpragma",
        "section": "",
        "mode": "man",
        "summary": "perlpragma - how to write a user pragma",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 5,
                "subsections": [
                    {
                        "name": "A basic example",
                        "lines": 109
                    },
                    {
                        "name": "Key naming",
                        "lines": 13
                    },
                    {
                        "name": "Implementation details",
                        "lines": 18
                    }
                ]
            }
        ],
        "sections": {
            "NAME": {
                "content": "perlpragma - how to write a user pragma\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "A pragma is a module which influences some aspect of the compile time or run time behaviour\nof Perl, such as \"strict\" or \"warnings\". With Perl 5.10 you are no longer limited to the\nbuilt in pragmata; you can now create user pragmata that modify the behaviour of user\nfunctions within a lexical scope.\n",
                "subsections": [
                    {
                        "name": "A basic example",
                        "content": "For example, say you need to create a class implementing overloaded mathematical operators,\nand would like to provide your own pragma that functions much like \"use integer;\" You'd like\nthis code\n\nuse MyMaths;\n\nmy $l = MyMaths->new(1.2);\nmy $r = MyMaths->new(3.4);\n\nprint \"A: \", $l + $r, \"\\n\";\n\nuse myint;\nprint \"B: \", $l + $r, \"\\n\";\n\n{\nno myint;\nprint \"C: \", $l + $r, \"\\n\";\n}\n\nprint \"D: \", $l + $r, \"\\n\";\n\nno myint;\nprint \"E: \", $l + $r, \"\\n\";\n\nto give the output\n\nA: 4.6\nB: 4\nC: 4.6\nD: 4\nE: 4.6\n\ni.e., where \"use myint;\" is in effect, addition operations are forced to integer, whereas by\ndefault they are not, with the default behaviour being restored via \"no myint;\"\n\nThe minimal implementation of the package \"MyMaths\" would be something like this:\n\npackage MyMaths;\nuse warnings;\nuse strict;\nuse myint();\nuse overload '+' => sub {\nmy ($l, $r) = @;\n# Pass 1 to check up one call level from here\nif (myint::ineffect(1)) {\nint($$l) + int($$r);\n} else {\n$$l + $$r;\n}\n};\n\nsub new {\nmy ($class, $value) = @;\nbless \\$value, $class;\n}\n\n1;\n\nNote how we load the user pragma \"myint\" with an empty list \"()\" to prevent its \"import\"\nbeing called.\n\nThe interaction with the Perl compilation happens inside package \"myint\":\n\npackage myint;\n\nuse strict;\nuse warnings;\n\nsub import {\n$^H{\"myint/ineffect\"} = 1;\n}\n\nsub unimport {\n$^H{\"myint/ineffect\"} = 0;\n}\n\nsub ineffect {\nmy $level = shift // 0;\nmy $hinthash = (caller($level))[10];\nreturn $hinthash->{\"myint/ineffect\"};\n}\n\n1;\n\nAs pragmata are implemented as modules, like any other module, \"use myint;\" becomes\n\nBEGIN {\nrequire myint;\nmyint->import();\n}\n\nand \"no myint;\" is\n\nBEGIN {\nrequire myint;\nmyint->unimport();\n}\n\nHence the \"import\" and \"unimport\" routines are called at compile time for the user's code.\n\nUser pragmata store their state by writing to the magical hash \"%^H\", hence these two\nroutines manipulate it. The state information in \"%^H\" is stored in the optree, and can be\nretrieved read-only at runtime with \"caller()\", at index 10 of the list of returned results.\nIn the example pragma, retrieval is encapsulated into the routine \"ineffect()\", which takes\nas parameter the number of call frames to go up to find the value of the pragma in the user's\nscript. This uses \"caller()\" to determine the value of $^H{\"myint/ineffect\"} when each line\nof the user's script was called, and therefore provide the correct semantics in the\nsubroutine implementing the overloaded addition.\n"
                    },
                    {
                        "name": "Key naming",
                        "content": "There is only a single \"%^H\", but arbitrarily many modules that want to use its scoping\nsemantics.  To avoid stepping on each other's toes, they need to be sure to use different\nkeys in the hash.  It is therefore conventional for a module to use only keys that begin with\nthe module's name (the name of its main package) and a \"/\" character.  After this module-\nidentifying prefix, the rest of the key is entirely up to the module: it may include any\ncharacters whatsoever.  For example, a module \"Foo::Bar\" should use keys such as\n\"Foo::Bar/baz\" and \"Foo::Bar/$%/!\".  Modules following this convention all play nicely with\neach other.\n\nThe Perl core uses a handful of keys in \"%^H\" which do not follow this convention, because\nthey predate it.  Keys that follow the convention won't conflict with the core's historical\nkeys.\n"
                    },
                    {
                        "name": "Implementation details",
                        "content": "The optree is shared between threads.  This means there is a possibility that the optree will\noutlive the particular thread (and therefore the interpreter instance) that created it, so\ntrue Perl scalars cannot be stored in the optree.  Instead a compact form is used, which can\nonly store values that are integers (signed and unsigned), strings or \"undef\" - references\nand floating point values are stringified.  If you need to store multiple values or complex\nstructures, you should serialise them, for example with \"pack\".  The deletion of a hash key\nfrom \"%^H\" is recorded, and as ever can be distinguished from the existence of a key with\nvalue \"undef\" with \"exists\".\n\nDon't attempt to store references to data structures as integers which are retrieved via\n\"caller\" and converted back, as this will not be threadsafe.  Accesses would be to the\nstructure without locking (which is not safe for Perl's scalars), and either the structure\nhas to leak, or it has to be freed when its creating thread terminates, which may be before\nthe optree referencing it is deleted, if other threads outlive it.\n\n\n\nperl v5.34.0                                 2025-07-25                                PERLPRAGMA(1)"
                    }
                ]
            }
        }
    }
}