README.md
1# NAME
2
3Devel::InheritNamespace - Inherit An Entire Namespace
4
5# SYNOPSIS
6
7 use Devel::InheritNamespace;
8
9 my $din = Devel::InheritNamespace->new(
10 on_class_found => sub { ... },
11 );
12 my @modules =
13 $din->all_modules( 'MyApp', 'Parent::Namespace1', 'Parent::Namespace2' );
14
15# DESCRIPTION
16
17WARNING: YMMV using this module.
18
19This module allows you to dynamically "inherit" an entire namespace.
20
21For example, suppose you have a set of packages under MyApp::Base:
22
23 MyApp::Base::Foo
24 MyApp::Base::Bar
25 MyApp::Base::Baz
26
27Then some time later you start writing MyApp::Extend.
28You want to reuse MyApp::Base::Foo and MyApp::Base::Bar by subclassing
29(because somehow the base namespace matters -- say, in Catalyst), but
30you want to put a little customization for MyApp::Base::Baz
31
32Normally you achieve this by manually creating MyApp::Extended:: modules:
33
34 # in MyApp/Extended/Foo.pm
35 package MyApp::Extended::Foo;
36 use Moose;
37 extends 'MyApp::Base::Foo';
38
39 # in MyApp/Extended/Bar.pm
40 package MyApp::Extended::Bar;
41 use Moose;
42 extends 'MyApp::Base::Bar';
43
44 # in MyApp/Extended/Baz.pm
45 package MyApp::Extended::Baz;
46 use Moose;
47 extends 'MyApp::Base::Baz';
48
49 ... whatever customization you need ...
50
51This is okay for a small number of modules, or if you are only doing this once
52or twice. But perhaps you have tens of these modules, or maybe you do this
53on every new project you create to inherit from a base applicatin set.
54
55In that case you can use Devel::InheritNamespace.
56
57# METHODS
58
59## `$class->new(%options)`
60
61Constructs a new Devel::InheritNamespace instance. You may pass the following
62options:
63
64- except
65
66 Regular expression to stop certain modules to be included in the search list.
67 Note: This option will probably be deleted in the future releases: see
68 `search_options` and Module::Pluggable for a way to achieve this.
69
70- on\_class\_found
71
72 Callback that gets called when a new class was loaded.
73
74- search\_options
75
76 Extra arguments to pass to Module::Pluggable::Object to search for modules.
77
78## `$self->all_modules( $main_namespace, @namespaces_to_inherit )`;
79
80Loads modules based on the following heuristics:
81
82 1. Search all modules in $main_namespace using Module::Pluggable.
83 2. Load those modules
84 3. Repease searching in namespaces declared in the @namespaces_to_inherit
85 4. Check if the corresponding module in the $main_namespace exists.
86 (we basically do $class =~ s/^$current_namespace/$main_namespace/)
87 5. If the module is already loaded, skip and check the module
88 6. If the module has not been loaded, dynamically create a module in
89 the $main_namespace, inheriting from the original one.
90 7. Repeat above for all namespaces.
91
92# TODO
93
94Documentation. Samples. Tests.
95
96# AUTHOR
97
98Daisuke Maki `<daisuke@endeworks.jp>`
99
100# LICENSE
101
102This program is free software; you can redistribute it and/or modify it
103under the same terms as Perl itself.
104
105See http://www.perl.com/perl/misc/Artistic.html
106