{"id":18779365,"url":"https://github.com/zostay/bolts","last_synced_at":"2026-07-04T17:31:11.637Z","repository":{"id":20158906,"uuid":"23429489","full_name":"zostay/Bolts","owner":"zostay","description":"An Inversion of Control framework for Perl","archived":false,"fork":false,"pushed_at":"2015-05-30T19:06:54.000Z","size":504,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-29T10:29:06.904Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zostay.png","metadata":{"files":{"readme":"README.pod","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-08-28T13:47:31.000Z","updated_at":"2023-11-20T22:37:03.000Z","dependencies_parsed_at":"2022-07-25T12:33:09.162Z","dependency_job_id":null,"html_url":"https://github.com/zostay/Bolts","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2FBolts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2FBolts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2FBolts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2FBolts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zostay","download_url":"https://codeload.github.com/zostay/Bolts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239690598,"owners_count":19681129,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T20:19:45.141Z","updated_at":"2025-10-29T06:42:28.410Z","avatar_url":"https://github.com/zostay.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"=pod\n\n=encoding UTF-8\n\n=head1 NAME\n\nBolts - An Inversion of Control framework for Perl\n\n=head1 VERSION\n\nversion 0.142930\n\n=head1 SYNOPSIS\n\n    package MyApp;\n    use Bolts;\n\n    artifcat log_file =\u003e 'var/messages.log';\n    artifact logger   =\u003e (\n        class =\u003e 'MyApp::Logger',\n        scope =\u003e 'singleton',\n        infer =\u003e 'acquisition',\n    );\n\n    # Later...\n    my $log = $app-\u003eacquire('logger');\n    $log-\u003eerror(\"Bad stuff.\");\n\n=head1 DESCRIPTION\n\nB\u003cCaution:\u003e I\u003c\u003c This is an B\u003cexperimental\u003e API. Some aspects of the API may change, possibly drastically, from version to version. That probably won't happen, but please contact me via email if you plan to use this in something and want to know what might change. Pay close attention to any B\u003cCaution\u003e remarks in the documentation. \u003e\u003e\n\nThis is yet another Inversion of Control framework for Perl. This one is based upon a combination of L\u003cBread::Board\u003e, concepts from the Spring framework, and a good mix of my own ideas and modifications after spending a few years using L\u003cMoose\u003e and Bread::Board.\n\n=head2 Inversion of Control\n\nFor those who might now know what Inversion of Control (IOC) is, it is a design pattern aimed at helping you decouple your code, automate parts of the configuration assembly, and manage the life cycle of your objects.\n\nBy using an IOC framework, the objects in your program need to know less about the other objects in your application. Your objects can focus on knowing what it needs from other objects without knowing where to find objects that do that or how they are configured. \n\nFor example, early in a programs lifetime, the logger might be a local object that writes directly to a file. Later, it might be an object with the same interface, but it writes to syslog. Further on, it might be some sort of logging service that is accessed over the network through a stub provided by a service locator. If your program uses an IOC framework, the configuration files for your IOC will change to pass a different object to the application during each phase, but the program itself might not change at all.\n\nAn IOC framework also helps you assemble complex configuration related to your application. It can join various configurations together in interesting and complex ways automatically.\n\nAn IOC framework can make sure that your objects live only as long as they should or longer than they would normally. It can manage the list of objects that should be created each time (prototypes), objects that should last as long as a user session, objects that should last as long as some request, and objects that last for the duration of the process (singletons).\n\nThe next sections will introduce the concepts and terminology used by this framework.\n\n=head2 Artifacts\n\nThe basic building block of the Bolts IOC framework is the B\u003cartifact\u003e. At the simplest level, an artifact is any kind of thing your program might use. It might be a value, it might be a reference to something, it might be an object, or it might be something more complex.\n\nFor simple values and direct references to things, you can treat any thing as an artifact. However, the real power starts when you use an implementation of L\u003cBolts::Role::Artifact\u003e, usually L\u003cBolts::Artifact\u003e to manage that thing. These provide utilities for constructing an object or other value according to some set of instructions and directions for managing the lifecycle of the artifact in question.\n\n=head2 Bags\n\nArtifacts are grouped into bags. A B\u003cbag\u003e can be any object, hash reference, or array reference. Artifacts are associated with the bag as indexes in the array, keys on the hash, or methods on the object. Literally, any object can be used as a bag, which differs from frameworks like L\u003cBread::Board\u003e, which requires that its services be put inside a special container object. Bolts just uses hashes, arrays, and objects in the usual Perl way to locate artifacts.\n\n=head2 Locators\n\nA B\u003clocator\u003e is an object that finds things in a bag (these are things related to L\u003cBolts::Role::Locator\u003e. The finding process is called, B\u003cacquisition\u003e. (If you are familiar with Harry Potter, this process is similar to Harry Potter using a wand to extract dittany from Hermione's handbag by saying \"Accio Dittany.\") After finding the object, the locator performs B\u003cresolution\u003e, which checks to see if returned artifact needs to be resolved further. (To continue the analogy, this is like unbottling the dittany and pouring it out, there may be another step before the artifact is completely ready for use.)\n\n=head2 Blueprints\n\nAttached to L\u003cBolts::Artifact\u003e definitions are a set of blueprints (some object that implements L\u003cBolts::Blueprint\u003e). A B\u003cblueprint\u003e describes how an artifact is located or constructed, which is part of resolution. The system provides standard blueprints that can cover all possible needs, but you can create your own to extend the framework as necessary. The built-in blueprints can locate an object by acquring it from a bag, the result of a subroutine, by use of a factory method or constructor on an object, by directly handing the value in to the bag when the bag is constructed, or set as a constant.\n\n=head2 Injectors\n\nAnother step in resolution is injection. An B\u003cinjector\u003e associates additional artifacts with the artifact being resolved. This might be values that need to be passed to the artifact during construction, methods that need to be called to configure the object following construction, or even keys on a hash that need to be set on the artifact.\n\nInjectors come in two flavors, injection by automatic acquisition and by given options. With acquisition, the framework will acquire or other provide addition artifacts to the artifact being resolved automatically, this is where much of the power of IOC comes from. Sometimes, however, an object just requires some configuration state to let it know how it will be used. In those cases, options can be directly passed to C\u003cacquire\u003e to be used for injection.\n\n=head2 Scope\n\nThe B\u003cscope\u003e of an artifact determines during what period an artifact is valid. Bolts provides two built-in scopes, prototype and singleton. A prototype represents an artifact that must be resolved every time it is acquired. A singleton represents an artifact that is resolved only the first time it is acquired and is then reused for all following acquisitions for the lifetime of the bag.\n\n=head2 Infererer\n\nIt is usually considered a bad thing in computer science if you have to configure something twice in the same program. Such duplication is tedious and leads to technical debt. This, unfortunately, is often the case when using some IOC frameworks. You configure the object once using Moose and then a second time to let the IOC framework know how to inject configuration into the artifact. This is where the inferers come in.\n\nAn B\u003cinferer\u003e is a tool that can inspect an object and automatically decide how that object should be configured. Bolts provides an inferer for L\u003cMoose\u003e that can use the metadata about a L\u003cMoose\u003e object to determine how to inject into that object automatically.\n\n=head2 Meta Locator and Extension\n\nOne of the goals of this system is to have the system rely on the IOC internally as much as possible and to decouple the components as much as possible. This goal has not been totally achieved, but it is something strived for. The framework itself depends on L\u003cBolts::Meta::Locator\u003e, which provides all the standard definitions internally. This can be extended to provide additional or even alternate features.\n\nAll the various components: artifact, bag, locator, blueprint, injector, scope, and inferer are completely extensible. You can create new versions of L\u003cBolts::Role::Artifact\u003e. You can create bags from almost anything. You can create new locators via L\u003cBolts::Role::Locator\u003e. You can create new blueprints via L\u003cBolts::Blueprint\u003e. You can create new scopes via L\u003cBolts::Scope\u003e. You can create new inferers via L\u003cBolts::Inferer\u003e. You can then associate these components with the internals using L\u003cBolts::Meta::Locator\u003e.\n\n=head1 THIS CLASS\n\nThe purpose of the Bolts module itself is to provide some nice syntactic sugar for turning the class that uses it into a bag and locator.\n\n=head1 FUNCTIONS\n\n=head2 artifact\n\n    artifact 'name';\n    artifact name =\u003e $value;\n    artifact name =\u003e %options;\n\nThis defines an artifact in the current class. This will create a method on the current object with the given \"name\". If only the name is given, then the artifact to use must be passed when the bag is constructed.\n\n    # for example, if you bag is named \"MyApp\"\n    my $bag = MyApp-\u003enew( name =\u003e 42 );\n    my $value = $bag-\u003eacquire('name');\n    say $value; # 42\n\nIf a scalar or reference is passed in as a single argument in addition to the name, the artifact will be set to that literal value.\n\nOtherwise, you may pass in a list of pairs, which will be interpreted depending on the keys present. Here is a list of keys and their meanings:\n\n=over\n\n=item path\n\nThis is like an alias to an artifact elsewhere within this bag or in another bag (if \"locator\" is passed as well). It is set to a reference to an array of names, naming the path within the bag to acquire. See L\u003cBolts::Blueprint::Acquired\u003e for details.\n\n=item value\n\nThis sets the artifact to a literal value, similar to passing C\u003c$value\u003e in the example above. See L\u003cBolts::Blueprint::Literal\u003e for details.\n\n=item class\n\nThis should be set to a package name. This causes the artifact to construct and return the value from a factory method or constructor. See L\u003cBolts::Blueprint::Factory\u003e for details.\n\n=item builder\n\nThis should be set to a subroutine. The subroutine will be called to attain this artifact and the return value used as the artifact. See L\u003cBolts::Blueprint::Builder\u003e for details.\n\n=item blueprint\n\nThis is set to the name of a L\u003cBolts::Blueprint\u003e definition and allows you to specify the blueprint you wish to use directly.\n\n=item scope\n\nIn addition to the options above, you may also specify the scope. This is usually either \"prototype\" or \"singleton\" and the default is generally \"prototype\".\n\n=back\n\n=head2 bag\n\n    bag 'name' =\u003e contains {\n        artifact 'child_name' =\u003e 42;\n    };\n\nAttaches a bag at the named location. This provides tools for assembling complex IOC configurations.\n\n=head2 such_that_each\n\n    bag 'name' =\u003e contains {\n        artifact 'child_name' =\u003e 'value';\n\n    } such_that_each {\n        isa =\u003e 'Str',\n    };\n\nCauses every artifact within the bag to have the same type constraints, which is handy in some cases. The first argument is a hash that may contain an C\u003cisa\u003e key and a C\u003cdoes\u003e key, which will be applid to each of the artifacts within. The second argument is the bag definition, which should be built using C\u003ccontains\u003e as shown in the description of L\u003c/bag\u003e.\n\n=head2 builder\n\n    artifact name =\u003e (\n        ...\n        parameters =\u003e {\n            thing =\u003e builder {\n                return MyApp::Thing-\u003enew,\n            },\n        },\n    );\n\nThis is a helper for setting a L\u003cBolts::Blueprint::BuiltInjector\u003e for use in passing in a dependency that is wired directly to the builder function given.\n\n=head2 dep\n\n    artifact other =\u003e ( ... );\n\n    artifact name =\u003e (\n        ...\n        parameters =\u003e {\n            thing =\u003e dep('other'),\n        },\n    );\n\nThis is a helper for laoding dependencies from a path in the current bag (or a bag within it).\n\n=head2 option\n\n    artifact name =\u003e (\n        ...\n        parameters =\u003e {\n            thing =\u003e option {\n                isa      =\u003e 'MyApp::Thing',\n                required =\u003e 1,\n            },\n            other_thing =\u003e option {\n                does     =\u003e 'MyApp::OtherThing',\n            },\n        },\n    );\n\nHelper to allow a dependency to be passed as a given option to the call to L\u003cBolts::Role::Locator/acquire\u003e. To provide validators for the values pass, you may set the C\u003cisa\u003e and C\u003cdoes\u003e options to a L\u003cMoose\u003e type constraint. To make the option required, set the C\u003crequired\u003e option.\n\n=head2 value\n\n    artifact name =\u003e (\n        ...\n        parameters =\u003e {\n            thing =\u003e value 42,\n        },\n    );\n\nHelper that passes a literal value through as a dependency to the artifact\nduring injection.\n\n=head2 self\n\n    artifact thing =\u003e (\n        ...\n        parameters =\u003e {\n            parent =\u003e self, \n        },\n    );\n\nSets up a blueprint to return the artifact's parent.    \n\n=head1 GLOBALS\n\n=head2 $Bolts::GLOBAL_FALLBACK_META_LOCATOR\n\nB\u003cSubject to Change:\u003e This is the name of the locator to use for locating the meta objects needed to configure within Bolts. The default is L\u003cBolts::Meta::Locator\u003e, which defines the standard set of scopes, blueprints, etc.\n\nThis is variable likely to change or disappear in the future.\n\n=for Pod::Coverage     contains\n\n=head1 AUTHOR\n\nAndrew Sterling Hanenkamp \u003chanenkamp@cpan.org\u003e\n\n=head1 COPYRIGHT AND LICENSE\n\nThis software is copyright (c) 2014 by Qubling Software LLC.\n\nThis is free software; you can redistribute it and/or modify it under\nthe same terms as the Perl 5 programming language system itself.\n\n=cut\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzostay%2Fbolts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzostay%2Fbolts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzostay%2Fbolts/lists"}