{
    "content": [
        {
            "type": "text",
            "text": "# Class::Container (perldoc)\n\n## NAME\n\nClass::Container - Glues object frameworks together transparently\n\n## SYNOPSIS\n\npackage Car;\nuse Class::Container;\n@ISA = qw(Class::Container);\nPACKAGE->validparams\n(\npaint  => {default => 'burgundy'},\nstyle  => {default => 'coupe'},\nwindshield => {isa => 'Glass'},\nradio  => {isa => 'Audio::Device'},\n);\nPACKAGE->containedobjects\n(\nwindshield => 'Glass::Shatterproof',\nwheel      => { class => 'Vehicle::Wheel',\ndelayed => 1 },\nradio      => 'Audio::MP3',\n);\nsub new {\nmy $package = shift;\n# 'windshield' and 'radio' objects are created automatically by\n# SUPER::new()\nmy $self = $package->SUPER::new(@);\n$self->{rightwheel} = $self->createdelayedobject('wheel');\n... do any more initialization here ...\nreturn $self;\n}\n\n## DESCRIPTION\n\nThis class facilitates building frameworks of several classes that inter-operate. It was first\ndesigned and built for \"HTML::Mason\", in which the Compiler, Lexer, Interpreter, Resolver,\nComponent, Buffer, and several other objects must create each other transparently, passing the\nappropriate parameters to the right class, possibly substituting other subclasses for any of\nthese objects.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION** (1 subsections)\n- **METHODS**\n- **SEE ALSO**\n- **AUTHOR**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Class::Container",
        "section": "",
        "mode": "perldoc",
        "summary": "Class::Container - Glues object frameworks together transparently",
        "synopsis": "package Car;\nuse Class::Container;\n@ISA = qw(Class::Container);\nPACKAGE->validparams\n(\npaint  => {default => 'burgundy'},\nstyle  => {default => 'coupe'},\nwindshield => {isa => 'Glass'},\nradio  => {isa => 'Audio::Device'},\n);\nPACKAGE->containedobjects\n(\nwindshield => 'Glass::Shatterproof',\nwheel      => { class => 'Vehicle::Wheel',\ndelayed => 1 },\nradio      => 'Audio::MP3',\n);\nsub new {\nmy $package = shift;\n# 'windshield' and 'radio' objects are created automatically by\n# SUPER::new()\nmy $self = $package->SUPER::new(@);\n$self->{rightwheel} = $self->createdelayedobject('wheel');\n... do any more initialization here ...\nreturn $self;\n}",
        "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": 32,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 17,
                "subsections": [
                    {
                        "name": "Scenario",
                        "lines": 21
                    }
                ]
            },
            {
                "name": "METHODS",
                "lines": 182,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 6,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 3,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Class::Container - Glues object frameworks together transparently\n",
                "subsections": []
            },
            "VERSION": {
                "content": "version 0.13\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "package Car;\nuse Class::Container;\n@ISA = qw(Class::Container);\n\nPACKAGE->validparams\n(\npaint  => {default => 'burgundy'},\nstyle  => {default => 'coupe'},\nwindshield => {isa => 'Glass'},\nradio  => {isa => 'Audio::Device'},\n);\n\nPACKAGE->containedobjects\n(\nwindshield => 'Glass::Shatterproof',\nwheel      => { class => 'Vehicle::Wheel',\ndelayed => 1 },\nradio      => 'Audio::MP3',\n);\n\nsub new {\nmy $package = shift;\n\n# 'windshield' and 'radio' objects are created automatically by\n# SUPER::new()\nmy $self = $package->SUPER::new(@);\n\n$self->{rightwheel} = $self->createdelayedobject('wheel');\n... do any more initialization here ...\nreturn $self;\n}\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This class facilitates building frameworks of several classes that inter-operate. It was first\ndesigned and built for \"HTML::Mason\", in which the Compiler, Lexer, Interpreter, Resolver,\nComponent, Buffer, and several other objects must create each other transparently, passing the\nappropriate parameters to the right class, possibly substituting other subclasses for any of\nthese objects.\n\nThe main features of \"Class::Container\" are:\n\n*   Explicit declaration of containment relationships (aggregation, factory creation, etc.)\n\n*   Declaration of constructor parameters accepted by each member in a class framework\n\n*   Transparent passing of constructor parameters to the class that needs them\n\n*   Ability to create one (automatic) or many (manual) contained objects automatically and\ntransparently\n",
                "subsections": [
                    {
                        "name": "Scenario",
                        "content": "Suppose you've got a class called \"Parent\", which contains an object of the class \"Child\", which\nin turn contains an object of the class \"GrandChild\". Each class creates the object that it\ncontains. Each class also accepts a set of named parameters in its \"new()\" method. Without using\n\"Class::Container\", \"Parent\" will have to know all the parameters that \"Child\" takes, and\n\"Child\" will have to know all the parameters that \"GrandChild\" takes. And some of the parameters\naccepted by \"Parent\" will really control aspects of \"Child\" or \"GrandChild\". Likewise, some of\nthe parameters accepted by \"Child\" will really control aspects of \"GrandChild\". So, what happens\nwhen you decide you want to use a \"GrandDaughter\" class instead of the generic \"GrandChild\"?\n\"Parent\" and \"Child\" must be modified accordingly, so that any additional parameters taken by\n\"GrandDaughter\" can be accommodated. This is a pain - the kind of pain that object-oriented\nprogramming was supposed to shield us from.\n\nNow, how can \"Class::Container\" help? Using \"Class::Container\", each class (\"Parent\", \"Child\",\nand \"GrandChild\") will declare what arguments they take, and declare their relationships to the\nother classes (\"Parent\" creates/contains a \"Child\", and \"Child\" creates/contains a\n\"GrandChild\"). Then, when you create a \"Parent\" object, you can pass \"Parent->new()\" all the\nparameters for all three classes, and they will trickle down to the right places. Furthermore,\n\"Parent\" and \"Child\" won't have to know anything about the parameters of its contained objects.\nAnd finally, if you replace \"GrandChild\" with \"GrandDaughter\", no changes to \"Parent\" or \"Child\"\nwill likely be necessary.\n"
                    }
                ]
            },
            "METHODS": {
                "content": "new()\nAny class that inherits from \"Class::Container\" should also inherit its \"new()\" method. You can\ndo this simply by omitting it in your class, or by calling \"SUPER::new(@)\" as indicated in the\nSYNOPSIS. The \"new()\" method ensures that the proper parameters and objects are passed to the\nproper constructor methods.\n\nAt the moment, the only possible constructor method is \"new()\". If you need to create other\nconstructor methods, they should call \"new()\" internally.\n\nPACKAGE->containedobjects()\nThis class method is used to register what other objects, if any, a given class creates. It is\ncalled with a hash whose keys are the parameter names that the contained class's constructor\naccepts, and whose values are the default class to create an object of.\n\nFor example, consider the \"HTML::Mason::Compiler\" class, which uses the following code:\n\nPACKAGE->containedobjects( lexer => 'HTML::Mason::Lexer' );\n\nThis defines the relationship between the \"HTML::Mason::Compiler\" class and the class it creates\nto go in its \"lexer\" slot. The \"HTML::Mason::Compiler\" class \"has a\" \"lexer\". The\n\"HTML::Mason::Compiler->new()\" method will accept a \"lexer\" parameter and, if no such parameter\nis given, an object of the \"HTML::Mason::Lexer\" class should be constructed.\n\nWe implement a bit of magic here, so that if \"HTML::Mason::Compiler->new()\" is called with a\n\"lexerclass\" parameter, it will load the indicated class (presumably a subclass of\n\"HTML::Mason::Lexer\"), instantiate a new object of that class, and use it for the Compiler's\n\"lexer\" object. We're also smart enough to notice if parameters given to\n\"HTML::Mason::Compiler->new()\" actually should go to the \"lexer\" contained object, and it will\nmake sure that they get passed along.\n\nFurthermore, an object may be declared as \"delayed\", which means that an object *won't* be\ncreated when its containing class is constructed. Instead, these objects will be created \"on\ndemand\", potentially more than once. The constructors will still enjoy the automatic passing of\nparameters to the correct class. See the \"createdelayedobject()\" for more.\n\nTo declare an object as \"delayed\", call this method like this:\n\nPACKAGE->containedobjects( train => { class => 'Big::Train',\ndelayed => 1 } );\n\nPACKAGE->validparams(...)\nSpecifies the parameters accepted by this class's \"new()\" method as a set of key/value pairs.\nAny parameters accepted by a superclass/subclass will also be accepted, as well as any\nparameters accepted by contained objects. This method is a get/set accessor method, so it\nreturns a reference to a hash of these key/value pairs. As a special case, if you wish to set\nthe valid params to an empty set and you previously set it to a non-empty set, you may call\n\"PACKAGE->validparams(undef)\".\n\n\"validparams()\" is called with a hash that contains parameter names as its keys and validation\nspecifications as values. This validation specification is largely the same as that used by the\n\"Params::Validate\" module, because we use \"Params::Validate\" internally.\n\nAs an example, consider the following situation:\n\nuse Class::Container;\nuse Params::Validate qw(:types);\nPACKAGE->validparams\n(\nallowglobals        => { type => ARRAYREF, parse => 'list',   default => [] },\ndefaultescapeflags => { type => SCALAR,   parse => 'string', default => '' },\nlexer                => { isa => 'HTML::Mason::Lexer' },\npreprocess           => { type => CODEREF,  parse => 'code',   optional => 1 },\npostprocessperl     => { type => CODEREF,  parse => 'code',   optional => 1 },\npostprocesstext     => { type => CODEREF,  parse => 'code',   optional => 1 },\n);\n\nPACKAGE->containedobjects( lexer => 'HTML::Mason::Lexer' );\n\nThe \"type\", \"default\", and \"optional\" parameters are part of the validation specification used\nby \"Params::Validate\". The various constants used, \"ARRAYREF\", \"SCALAR\", etc. are all exported\nby \"Params::Validate\". This means that any of these six parameter names, plus the \"lexerclass\"\nparameter (because of the \"containedobjects()\" specification given earlier), are valid\narguments to the Compiler's \"new()\" method.\n\nNote that there are also some \"parse\" attributes declared. These have nothing to do with\n\"Class::Container\" or \"Params::Validate\" - any extra entries like this are simply ignored, so\nyou are free to put extra information in the specifications as long as it doesn't overlap with\nwhat \"Class::Container\" or \"Params::Validate\" are looking for.\n\n$self->createdelayedobject()\nIf a contained object was declared with \"delayed => 1\", use this method to create an instance of\nthe object. Note that this is an object method, not a class method:\n\nmy $foo =       $self->createdelayedobject('foo', ...); # YES!\nmy $foo = PACKAGE->createdelayedobject('foo', ...); # NO!\n\nThe first argument should be a key passed to the \"containedobjects()\" method. Any additional\narguments will be passed to the \"new()\" method of the object being created, overriding any\nparameters previously passed to the container class constructor. (Could I possibly be more\nalliterative? Veni, vedi, vici.)\n\n$self->delayedobjectparams($name, [params])\nAllows you to adjust the parameters that will be used to create any delayed objects in the\nfuture. The first argument specifies the \"name\" of the object, and any additional arguments are\nkey-value pairs that will become parameters to the delayed object.\n\nWhen called with only a $name argument and no list of parameters to set, returns a hash\nreference containing the parameters that will be passed when creating objects of this type.\n\n$self->delayedobjectclass($name)\nReturns the class that will be used when creating delayed objects of the given name. Use this\nsparingly - in most situations you shouldn't care what the class is.\n\nPACKAGE->decorates()\nVersion 0.09 of Class::Container added [as yet experimental] support for so-called \"decorator\"\nrelationships, using the term as defined in *Design Patterns* by Gamma, et al. (the Gang of Four\nbook). To declare a class as a decorator of another class, simply set @ISA to the class which\nwill be decorated, and call the decorator class's \"decorates()\" method.\n\nInternally, this will ensure that objects are instantiated as decorators. This means that you\ncan mix & match extra add-on functionality classes much more easily.\n\nIn the current implementation, if only a single decoration is used on an object, it will be\ninstantiated as a simple subclass, thus avoiding a layer of indirection.\n\n$self->validationspec()\nReturns a hash reference suitable for passing to the \"Params::Validate\" \"validate\" function.\nDoes *not* include any arguments that can be passed to contained objects.\n\n$class->allowedparams(\\%args)\nReturns a hash reference of every parameter this class will accept, *including* parameters it\nwill pass on to its own contained objects. The keys are the parameter names, and the values are\ntheir corresponding specifications from their \"validparams()\" definitions. If a parameter is\nused by both the current object and one of its contained objects, the specification returned\nwill be from the container class, not the contained.\n\nBecause the parameters accepted by \"new()\" can vary based on the parameters *passed* to \"new()\",\nyou can pass any parameters to the \"allowedparams()\" method too, ensuring that the hash you get\nback is accurate.\n\n$self->container()\nReturns the object that created you. This is remembered by storing a reference to that object,\nso we use the \"Scalar::Utils\" \"weakref()\" function to avoid persistent circular references that\nwould cause memory leaks. If you don't have \"Scalar::Utils\" installed, we don't make these\nreferences in the first place, and calling \"container()\" will result in a fatal error.\n\nIf you weren't created by another object via \"Class::Container\", \"container()\" returns \"undef\".\n\nIn most cases you shouldn't care what object created you, so use this method sparingly.\n\n$object->showcontainers\n$package->showcontainers\nThis method returns a string meant to describe the containment relationships among classes. You\nshould not depend on the specific formatting of the string, because I may change things in a\nfuture release to make it prettier.\n\nFor example, the HTML::Mason code returns the following when you do \"$interp->showcontainers\":\n\nHTML::Mason::Interp=HASH(0x238944)\nresolver -> HTML::Mason::Resolver::File\ncompiler -> HTML::Mason::Compiler::ToObject\nlexer -> HTML::Mason::Lexer\nrequest -> HTML::Mason::Request (delayed)\nbuffer -> HTML::Mason::Buffer (delayed)\n\nCurrently, containment is shown by indentation, so the Interp object contains a resolver and a\ncompiler, and a delayed request (or several delayed requests). The compiler contains a lexer,\nand each request contains a delayed buffer (or several delayed buffers).\n\n$object->dumpparameters\nReturns a hash reference containing a set of parameters that should be sufficient to re-create\nthe given object using its class's \"new()\" method. This is done by fetching the current value\nfor each declared parameter (i.e. looking in $object for hash entries of the same name), then\nrecursing through all contained objects and doing the same.\n\nA few words of caution here. First, the dumped parameters represent the *current* state of the\nobject, not the state when it was originally created.\n\nSecond, a class's declared parameters may not correspond exactly to its data members, so it\nmight not be possible to recover the former from the latter. If it's possible but requires some\nmanual fudging, you can override this method in your class, something like so:\n\nsub dumpparameters {\nmy $self = shift;\nmy $dump = $self->SUPER::dumpparameters();\n\n# Perform fudgery\n$dump->{incoming} = $self->{private};\ndelete $dump->{superfluous};\nreturn $dump;\n}\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Params::Validate\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Originally by Ken Williams <ken@mathforum.org> and Dave Rolsky <autarch@urth.org> for the\nHTML::Mason project. Important feedback contributed by Jonathan Swartz <swartz@pobox.com>.\nExtended by Ken Williams for the AI::Categorizer project.\n\nCurrently maintained by Ken Williams.\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "This program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
                "subsections": []
            }
        }
    }
}