{"id":28373286,"url":"https://github.com/nigelhorne/object-configure","last_synced_at":"2025-10-11T04:20:16.652Z","repository":{"id":292041998,"uuid":"979632843","full_name":"nigelhorne/Object-Configure","owner":"nigelhorne","description":"Runtime configuration for an object","archived":false,"fork":false,"pushed_at":"2025-09-17T11:34:33.000Z","size":157,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-28T09:59:50.026Z","etag":null,"topics":["cpan","cpan-module","debug","debugging","perl","perl5"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nigelhorne.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-07T20:27:14.000Z","updated_at":"2025-09-17T11:34:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"b3c42330-acc3-4c81-993c-aae08a68d2be","html_url":"https://github.com/nigelhorne/Object-Configure","commit_stats":null,"previous_names":["nigelhorne/class-debug","nigelhorne/object-configure"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nigelhorne/Object-Configure","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FObject-Configure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FObject-Configure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FObject-Configure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FObject-Configure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nigelhorne","download_url":"https://codeload.github.com/nigelhorne/Object-Configure/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FObject-Configure/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006247,"owners_count":26084060,"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","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cpan","cpan-module","debug","debugging","perl","perl5"],"created_at":"2025-05-29T19:08:43.144Z","updated_at":"2025-10-11T04:20:16.640Z","avatar_url":"https://github.com/nigelhorne.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CPAN version](https://badge.fury.io/pl/Object-Configure.svg)](https://metacpan.org/pod/Object::Debug)\n![Perl CI](https://github.com/nigelhorne/Object-Configure/actions/workflows/perl-ci.yml/badge.svg)\n\n# NAME\n\nObject::Configure - Runtime Configuration for an Object\n\n# VERSION\n\n0.15\n\n# SYNOPSIS\n\nThe `Object::Configure` module is a lightweight utility designed to inject runtime parameters into other classes,\nprimarily by layering configuration and logging support,\nwhen instatiating objects.\n\n[Log::Abstraction](https://metacpan.org/pod/Log%3A%3AAbstraction) and [Config::Abstraction](https://metacpan.org/pod/Config%3A%3AAbstraction) are modules developed to solve a specific need:\nruntime configurability without needing to rewrite or hardcode behaviours.\nThe goal is to allow individual modules to enable or disable features on the fly, and to do it using whatever configuration system the user prefers.\n\nAlthough the initial aim was general configurability,\nthe primary use case that's emerged has been fine-grained logging control,\nmore flexible and easier to manage than what you'd typically do with [Log::Log4perl](https://metacpan.org/pod/Log%3A%3ALog4perl).\nFor example,\nyou might want one module to log verbosely while another stays quiet,\nand be able to toggle that dynamically - without making invasive changes to each module.\n\nTo tie it all together,\nthere is `Object::Configure`.\nIt sits on [Log::Abstraction](https://metacpan.org/pod/Log%3A%3AAbstraction) and [Config::Abstraction](https://metacpan.org/pod/Config%3A%3AAbstraction),\nand with just a couple of extra lines in a class constructor,\nyou can hook in this behaviour seamlessly.\nThe intent is to keep things modular and reusable,\nespecially across larger systems or in situations where you want user-selectable behaviour.\n\nAdd this to your constructor:\n\n    package My::Module;\n\n    use Object::Configure;\n    use Params::Get;\n\n    sub new {\n         my $class = shift;\n         my $params = Object::Configure::configure($class, @_ ? \\@_ : undef);    # Reads in the runtime configuration settings\n         # or my $params = Object::Configure::configure($class, { @_ });\n\n         return bless $params, $class;\n     }\n\nThroughout your class, add code such as:\n\n    sub method\n    {\n        my $self = shift;\n\n        $self-\u003e{'logger'}-\u003etrace(ref($self), ': ', __LINE__, ' entering method');\n    }\n\n## CHANGING BEHAVIOUR AT RUN TIME\n\n### USING A CONFIGURATION FILE\n\nTo control behavior at runtime, `Object::Configure` supports loading settings from a configuration file via [Config::Abstraction](https://metacpan.org/pod/Config%3A%3AAbstraction).\n\nA minimal example of a config file (`~/.conf/local.conf`) might look like:\n\n    [My__Module]\n    logger.file = /var/log/mymodule.log\n\nThe `configure()` function will read this file,\noverlay it onto your default parameters,\nand initialize the logger accordingly.\n\nIf the file is not readable and no config\\_dirs are provided,\nthe module will throw an error.\n\nThis mechanism allows dynamic tuning of logging behavior (or other parameters you expose) without modifying code.\n\nMore details to be written.\n\n### USING ENVIRONMENT VARIABLES\n\n`Object::Configure` also supports runtime configuration via environment variables,\nwithout requiring a configuration file.\n\nEnvironment variables are read automatically when you use the `configure()` function,\nthanks to its integration with [Config::Abstraction](https://metacpan.org/pod/Config%3A%3AAbstraction).\nThese variables should be prefixed with your class name, followed by a double colon.\n\nFor example, to enable syslog logging for your `My::Module` class,\nyou could set:\n\n    export My__Module__logger__file=/var/log/mymodule.log\n\nThis would be equivalent to passing the following in your constructor:\n\n     My::Module-\u003enew(logger =\u003e Log::Abstraction-\u003enew({ file =\u003e '/var/log/mymodule.log' });\n\nAll environment variables are read and merged into the default parameters under the section named after your class.\nThis allows centralized and temporary control of settings (e.g., for production diagnostics or ad hoc testing) without modifying code or files.\n\nNote that environment variable settings take effect regardless of whether a configuration file is used,\nand are applied during the call to `configure()`.\n\nMore details to be written.\n\n## HOT RELOAD\n\nHot reload is not supported on Windows.\n\n### Basic Hot Reload Setup\n\n    package My::App;\n    use Object::Configure;\n\n    sub new {\n        my $class = shift;\n        my $params = Object::Configure::configure($class, @_ ? \\@_ : undef);\n        my $self = bless $params, $class;\n\n        # Register for hot reload\n        Object::Configure::register_object($class, $self) if $params-\u003e{_config_file};\n\n        return $self;\n    }\n\n    # Optional: Define a reload hook\n    sub _on_config_reload {\n        my ($self, $new_config) = @_;\n        print \"My::App config was reloaded!\\n\";\n        # Custom reload logic here\n    }\n\n### Enable Hot Reload in Your Main Application\n\n    # Enable hot reload with custom callback\n    Object::Configure::enable_hot_reload(\n        interval =\u003e 5,  # Check every 5 seconds\n        callback =\u003e sub {\n            print \"Configuration files have been reloaded!\\n\";\n        }\n    );\n\n    # Your application continues running...\n    # Config changes will be automatically detected and applied\n\n### Manual Reload\n\n    # Manually trigger a reload\n    my $count = Object::Configure::reload_config();\n    print \"Reloaded configuration for $count objects\\n\";\n\n# SUBROUTINES/METHODS\n\n## configure\n\nConfigure your class at runtime with hot reload support.\n\nTakes arguments:\n\n- `class`\n- `params`\n\n    A hashref containing default parameters to be used in the constructor.\n\n- `carp_on_warn`\n\n    If set to 1, call `Carp:carp` on `warn()`.\n    This value is also read from the configuration file,\n    which will take precedence.\n\n- `logger`\n\n    The logger to use.\n    If none is given, an instatiation of [Log::Abstraction](https://metacpan.org/pod/Log%3A%3AAbstraction) will be created, unless the logger is set to NULL.\n\n- `schema`\n\n    A [Params::Validate::Strict](https://metacpan.org/pod/Params%3A%3AValidate%3A%3AStrict) compatible schema to validate the configuration file against.\n\nReturns a hash ref containing the new values for the constructor.\n\nNow you can set up a configuration file and environment variables to configure your object.\n\n## instantiate($class,...)\n\nCreate and configure an object of the given class.\nThis is a quick and dirty way of making third-party classes configurable at runtime.\n\n# HOT RELOAD FEATURES\n\n## enable\\_hot\\_reload\n\nEnable hot reloading for configuration files.\n\n    Object::Configure::enable_hot_reload(\n        interval =\u003e 5,  # Check every 5 seconds (default: 10)\n        callback =\u003e sub { print \"Config reloaded!\\n\"; }  # Optional callback\n    );\n\n## disable\\_hot\\_reload\n\nDisable hot reloading and stop the background watcher.\n\n    Object::Configure::disable_hot_reload();\n\n## reload\\_config\n\nManually trigger a configuration reload for all registered objects.\n\n    Object::Configure::reload_config();\n\n## register\\_object\n\nRegister an object for hot reload monitoring.\n\n    Object::Configure::register_object($class, $obj);\n\nThis is automatically called by the configure() function when a config file is used,\nbut can also be called manually to register objects for hot reload.\n\n## restore\\_signal\\_handlers\n\nRestore original signal handlers and disable hot reload integration.\nUseful when you want to cleanly shut down the hot reload system.\n\n    Object::Configure::restore_signal_handlers();\n\n## get\\_signal\\_handler\\_info\n\nGet information about the current signal handler setup.\nUseful for debugging signal handler chains.\n\n    my $info = Object::Configure::get_signal_handler_info();\n    print \"Original USR1 handler: \", $info-\u003e{original_usr1} || 'none', \"\\n\";\n    print \"Hot reload active: \", $info-\u003e{hot_reload_active} ? 'yes' : 'no', \"\\n\";\n\n# SEE ALSO\n\n- [Config::Abstraction](https://metacpan.org/pod/Config%3A%3AAbstraction)\n- [Log::Abstraction](https://metacpan.org/pod/Log%3A%3AAbstraction)\n- Test coverage report: [https://nigelhorne.github.io/Object-Configure/coverage/](https://nigelhorne.github.io/Object-Configure/coverage/)\n\n# SUPPORT\n\nThis module is provided as-is without any warranty.\n\nPlease report any bugs or feature requests to `bug-object-configure at rt.cpan.org`,\nor through the web interface at\n[http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Object-Configure](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Object-Configure).\nI will be notified, and then you'll\nautomatically be notified of progress on your bug as I make changes.\n\nYou can find documentation for this module with the perldoc command.\n\n    perldoc Object::Configure\n\n# LICENSE AND COPYRIGHT\n\nCopyright 2025 Nigel Horne.\n\nUsage is subject to licence terms.\n\nThe licence terms of this software are as follows:\n\n- Personal single user, single computer use: GPL2\n- All other users (including Commercial, Charity, Educational, Government)\n  must apply in writing for a licence for use from Nigel Horne at the\n  above e-mail.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigelhorne%2Fobject-configure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnigelhorne%2Fobject-configure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigelhorne%2Fobject-configure/lists"}