{
    "content": [
        {
            "type": "text",
            "text": "# Object::Realize::Later (perldoc)\n\n## NAME\n\nObject::Realize::Later - Delayed creation of objects\n\n## SYNOPSIS\n\npackage MyLazyObject;\nuse Object::Realize::Later\nbecomes => 'MyRealObject',\nrealize => 'load';\n\n## DESCRIPTION\n\nThe \"Object::Realize::Later\" class helps with implementing transparent on demand realization of\nobject data. This is related to the tricks on autoloading of data, the lesser known cousin of\nautoloading of functionality.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS** (4 subsections)\n- **DETAILS** (3 subsections)\n- **SEE ALSO**\n- **LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Object::Realize::Later",
        "section": "",
        "mode": "perldoc",
        "summary": "Object::Realize::Later - Delayed creation of objects",
        "synopsis": "package MyLazyObject;\nuse Object::Realize::Later\nbecomes => 'MyRealObject',\nrealize => 'load';",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 9,
                "subsections": []
            },
            {
                "name": "METHODS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Construction",
                        "lines": 1
                    },
                    {
                        "name": "use",
                        "lines": 43
                    },
                    {
                        "name": "Added to YOUR class",
                        "lines": 39
                    },
                    {
                        "name": "Object::Realize::Later internals",
                        "lines": 17
                    }
                ]
            },
            {
                "name": "DETAILS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "About lazy loading",
                        "lines": 36
                    },
                    {
                        "name": "Traps",
                        "lines": 41
                    },
                    {
                        "name": "Examples",
                        "lines": 137
                    }
                ]
            },
            {
                "name": "SEE ALSO",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "LICENSE",
                "lines": 5,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Object::Realize::Later - Delayed creation of objects\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "package MyLazyObject;\n\nuse Object::Realize::Later\nbecomes => 'MyRealObject',\nrealize => 'load';\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "The \"Object::Realize::Later\" class helps with implementing transparent on demand realization of\nobject data. This is related to the tricks on autoloading of data, the lesser known cousin of\nautoloading of functionality.\n\nOn demand realization is all about performance gain. Why should you spent costly time on\nrealizing an object, when the data on the object is never (or not yet) used? In interactive\nprograms, postponed realization may boost start-up: the realization of objects is triggered by\nthe use, so spread over time.\n",
                "subsections": []
            },
            "METHODS": {
                "content": "",
                "subsections": [
                    {
                        "name": "Construction",
                        "content": ""
                    },
                    {
                        "name": "use",
                        "content": "When you invoke (\"use\") the \"Object::Realize::Later\" package, it will add a set of methods\nto your package (see section \"Added to YOUR class\").\n\n-Option            --Default\nbecomes             <required>\nbelievecaller      <false>\nrealize             <required>\nsourcemodule       <becomes>\nwarnrealization    <false>\nwarnrealizeagain  <false>\n\nbecomes => CLASS\nWhich type will this object become after realization.\n\nbelievecaller => BOOLEAN\nWhen a method is called on the un-realized object, the AUTOLOAD checks whether this\nresolves the need. If not, the realization is not done. However, when realization may\nresult in an object that extends the functionality of the class specified with \"becomes\",\nthis check must be disabled. In that case, specify true for this option.\n\nrealize => METHOD|CODE\nHow will transform. If you specify a CODE reference, then this will be called with the\nlazy-object as first argument, and the requested method as second.\n\nAfter realization, you may still have your hands on the lazy object on various places. Be\nsure that your realization method is coping with that, for instance by using Memoize. See\nexamples below.\n\nsourcemodule => CLASS\nif the class (a package) is included in a file (module) with a different name, then use\nthis argument to specify the file name. The name is expected to be the same as in the\n\"require\" call which would load it.\n\nwarnrealization => BOOLEAN\nPrint a warning message when the realization starts. This is for debugging purposes.\n\nwarnrealizeagain => BOOLEAN\nWhen an object is realized, the original object -which functioned as a stub- is\nreconstructed to work as proxy to the realized object. This option will issue a warning\nwhen that proxy is used, which means that somewhere in your program there is a variable\nstill holding a reference to the stub. This latter is not problematic at all, although it\nslows-down each method call.\n"
                    },
                    {
                        "name": "Added to YOUR class",
                        "content": "$obj->AUTOLOAD()\nWhen a method is called which is not available for the lazy object, the AUTOLOAD is called.\n\n$obj->can($method)\nObject::Realize::Later->can($method)\nIs the specified $method available for the lazy or the realized version of this object? It\nwill return the reference to the code.\n\nexample:\n\nMyLazyObject->can('lazyWork')      # true\nMyLazyObject->can('realWork')      # true\n\nmy $lazy = MyLazyObject->new;\n$lazy->can('lazyWork');            # true\n$lazy->can('realWork');            # true\n\n$obj->forceRealize()\nYou can force the load by calling this method on your object. It returns the realized\nobject.\n\nObject::Realize::Later->isa($class)\nIs this object a (sub-)class of the specified $class or can it become a (sub-)class of\n$class.\n\nexample:\n\nMyLazyObject->isa('MyRealObject')      # true\nMyLazyObject->isa('SuperClassOfLazy'); # true\nMyLazyObject->isa('SuperClassOfReal'); # true\n\nmy $lazy = MyLazyObject->new;\n$lazy->isa('MyRealObject');            # true\n$lazy->isa('SuperClassOfLazy');        # true\n$lazy->isa('SuperClassOfReal');        # true\n\n$obj->willRealize()\nReturns which class will be the realized to follow-up this class.\n"
                    },
                    {
                        "name": "Object::Realize::Later internals",
                        "content": "The next methods are not exported to the class where the `use' took place. These methods\nimplement the actual realization.\n\nObject::Realize::Later->import(%options)\nThe %options used for \"import\" are the values after the class name with \"use\". So this\nroutine implements the actual option parsing. It generates code dynamically, which is then\nevaluated in the callers name-space.\n\nObject::Realize::Later->realizationOf( $object, [$realized] )\nReturns the $realized version of $object, optionally after setting it first. When the method\nreturns \"undef\", the realization has not yet taken place or the realized object has already\nbeen removed again.\n\nObject::Realize::Later->realize(%options)\nThis method is called when a \"$object-\"forceRealize()> takes place. It checks whether the\nrealization has been done already (is which case the realized object is returned)\n"
                    }
                ]
            },
            "DETAILS": {
                "content": "",
                "subsections": [
                    {
                        "name": "About lazy loading",
                        "content": "There are two ways to implement lazy behaviour: you may choose to check whether you have\nrealized the data in each method which accesses the data, or use the autoloading of data trick.\n\nAn implementation of the first solution is:\n\nsub realize {\nmy $self = shift;\nreturn $self unless $self->{isrealized};\n\n# read the data from file, or whatever\n$self->{data} = ....;\n\n$self->{isrealized} = 1;\n$self;\n}\n\nsub getData() {\nmy $self = shift;\nreturn $self->realize->{data};\n}\n\nThe above implementation is error-prone, where you can easily forget to call realize(). The\ntests cannot cover all ordenings of method-calls to detect the mistakes.\n\nThe *second approach* uses autoloading, and is supported by this package. First we create a\nstub-object, which will be transformable into a realized object later. This transformation is\ntriggered by AUTOLOAD.\n\nThis stub-object may contain some methods from the realized object, to reduce the need for\nrealization. The stub will also contain some information which is required for the creation of\nthe real object.\n\n\"Object::Realize::Later\" solves the inheritance problems (especially the isa() and can()\nmethods) and supplies the AUTOLOAD method. Class methods which are not defined in the stub\nobject are forwarded as class methods without realization.\n"
                    },
                    {
                        "name": "Traps",
                        "content": "Be aware of dangerous traps in the current implementation. These problems appear by having\nmultiple references to the same delayed object. Depending on how the realization is implemented,\nterrible things can happen.\n\nThe two versions of realization:\n\n*   by reblessing\n\nThis is the safe version. The realized object is the same object as the delayed one, but\nreblessed in a different package. When multiple references to the delayed object exists,\nthey will all be updated at the same, because the bless information is stored within the\nrefered variable.\n\n*   by new instance\n\nThis is the nicest way of realization, but also quite more dangerous. Consider this:\n\npackage Delayed;\nuse Object::Realize::Later\nbecomes => 'Realized',\nrealize => 'load';\n\nsub new($)      {my($class,$v)=@; bless {label=>$v}, $class}\nsub setLabel($) {my $self = shift; $self->{label} = shift}\nsub load()      {$[0] = Realized->new($[0]->{label}) }\n\npackage Realized;  # file Realized.pm or use use(sourcemodule)\nsub new($)      {my($class,$v)=@; bless {label=>$v}, $class}\nsub setLabel($) {my $self = shift; $self->{label} = shift}\nsub getLabel()  {my $self = shift; $self->{label}}\n\npackage main;\nmy $original = Delayed->new('original');\nmy $copy     = $original;\nprint $original->getLabel;     # prints 'original'\nprint ref $original;           # prints 'Realized'\nprint ref $copy;               # prints 'Delayed'\n$original->setLabel('changed');\nprint $original->getLabel;     # prints 'changed'\nprint $copy->getLabel;         # prints 'original'\n"
                    },
                    {
                        "name": "Examples",
                        "content": "Example 1\nIn the first example, we delay-load a message. On the moment the message is defined, we only\ntake the location. When the data of the message is taken (header or body), the data is\nautoloaded.\n\npackage Mail::Message::Delayed;\n\nuse Object::Realize::Later\n( becomes => 'Mail::Message::Real'\n, realize => 'loadMessage'\n);\n\nsub new($) {\nmy ($class, $file) = @;\nbless { filename => $file }, $class;\n}\n\nsub loadMessage() {\nmy $self = shift;\nMail::Message::Real->new($self->{filename});\n}\n\nIn the main program:\n\npackage main;\nuse Mail::Message::Delayed;\n\nmy $msg    = Mail::Message::Delayed->new('/home/user/mh/1');\n$msg->body->print;     # this will trigger autoload.\n\nExample 2\nYour realization may also be done by reblessing. In that case to change the type of your object\ninto a different type which stores the same information. Is that right? Are you sure? For simple\ncases, this may be possible:\n\npackage Alive;\nuse Object::Realize::Later\nbecomes => 'Dead',\nrealize => 'kill';\n\nsub new()         {my $class = shift; bless {@}, $class}\nsub jump()        {print \"Jump!\\n\"}\nsub showAntlers() {print \"Fight!\\n\"}\nsub kill()        {bless(shift, 'Dead')}\n\npackage Dead;\nsub takeAntlers() {...}\n\nIn the main program:\n\nmy $deer   = Alive->new(Animal => 'deer');\nmy $trophy = $deer->takeAntlers();\n\nIn this situation, the object (reference) is not changed but is *reblessed*. There is no danger\nthat the un-realized version of the object is kept somewhere: all variable which know about this\npartical *deer* see the change.\n\nExample 3\nThis module is especially useful for larger projects, which there is a need for speed or memory\nreduction. In this case, you may have an extra overview on which objects have been realized\n(transformed), and which not. This example is taken from the MailBox modules:\n\nThe Mail::Box module tries to boost the access-time to a folder. If you only need the messages\nof the last day, why shall all be read? So, MailBox only creates an invertory of messages at\nfirst. It takes the headers of all messages, but leaves the body (content) of the message in the\nfile.\n\nIn MailBox' case, the Mail::Message-object has the choice between a number of\nMail::Message::Body's, one of which has only be prepared to read the body when needed. A code\nsnippet:\n\npackage Mail::Message;\nsub new($$)\n{   my ($class, $head, $body) = @;\nmy $self = bless {head => $head, body => $body}, $class;\n$body->message($self);          # tell body about the message\n}\nsub head()     { shift->{head} }\nsub body()     { shift->{body} }\n\nsub loadBody()\n{   my $self = shift;\nmy $body = $self->body;\n\n# Catch re-invocations of the loading.  If anywhere was still\n# a reference to the old (unrealized) body of this message, we\n# return the new-one directly.\nreturn $body unless $body->can('forceRealize');\n\n# Load the body (change it to anything which really is of\n# the promised type, or a sub-class of it.\nmy ($lines, $size) = .......;    # get the data\n$self->{body} = Mail::Message::Body::Lines\n->new($lines, $size, $self);\n\n# Return the realized object.\nreturn $self->{body};\n}\n\npackage Mail::Message::Body::Lines;\nuse base 'Mail::Message::Body';\n\nsub new($$$)\n{   my ($class, $lines, $size, $message) = @;\nbless { lines => $lines, size => $size\n, message => $message }, $class;\n}\nsub size()    { shift->{size} }\nsub lines()   { shift->{lines} }\nsub message() { shift->{message);\n\npackage Mail::Message::Body::Delayed;\nuse Object::Realize::Later\nbecomes => 'Mail::Message::Body',\nrealize => sub {shift->message->loadBody};\n\nsub new($)\n{   my ($class, $size) = @;\nbless {size => $size}, $class;\n}\nsub size() { shift->{size} }\nsub message(;$)\n{   my $self = shift;\n@ ? ($self->{message} = shift) : $self->{messages};\n}\n\npackage main;\nuse Mail::Message;\nuse Mail::Message::Body::Delayed;\n\nmy $body    = Mail::Message::Body::Delayed->new(42);\nmy $message = Mail::Message->new($head, $body);\n\nprint $message->size;         # will not trigger realization!\nprint $message->can('lines'); # true, but no realization yet.\nprint $message->lines;        # realizes automatically.\n"
                    }
                ]
            },
            "SEE ALSO": {
                "content": "This module is part of Object-Realize-Later distribution version 0.21, built on January 24,\n2018. Website: http://perl.overmeer.net/CPAN/\n",
                "subsections": []
            },
            "LICENSE": {
                "content": "Copyrights 2001-2018 by [Mark Overmeer]. For other contributors see ChangeLog.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself. See http://dev.perl.org/licenses/\n",
                "subsections": []
            }
        }
    }
}