| 1 | package Module::Install::DBICx::AutoDoc; | ||
| 2 | |||
| 3 | |||
| 4 | BEGIN { | ||
| 5 | use 5.004; | ||
| 6 | use strict; | ||
| 7 | use warnings; | ||
| 8 | |||
| 9 | use Data::Dump qw/dump/; | ||
| 10 | use DBICx::AutoDoc; # if this fails this module fails | ||
| 11 | |||
| 12 | use base 'Module::Install::Base'; | ||
| 13 | |||
| 14 | our $VERSION = '0.03'; | ||
| 15 | use vars qw/$SCHEMA $AUTODOC_OUTPUT/; | ||
| 16 | } | ||
| 17 | |||
| 18 | =head1 NAME | ||
| 19 | |||
| 20 | Module::Install::DBICx::AutoDoc - Use your Makefile to run DBICx::AutoDoc | ||
| 21 | |||
| 22 | =head1 VERSION | ||
| 23 | |||
| 24 | Version 0.03 | ||
| 25 | |||
| 26 | =head1 SYNOPSIS | ||
| 27 | |||
| 28 | In MakeFile.PL: | ||
| 29 | |||
| 30 | dbicx_autodoc('doc'); # use name() or module_name() as Schema package | ||
| 31 | # or | ||
| 32 | dbicx_autodoc('doc','My::Schema'); # better be in lib/ | ||
| 33 | # or | ||
| 34 | dbicx_autodoc({ | ||
| 35 | output => 'doc', | ||
| 36 | schema => 'My::Schema' | ||
| 37 | }); | ||
| 38 | |||
| 39 | From CLI: | ||
| 40 | |||
| 41 | make autodoc | ||
| 42 | |||
| 43 | =head1 METHODS | ||
| 44 | |||
| 45 | =head2 dbicx_autodoc | ||
| 46 | |||
| 47 | Add a DBICx::AutoDoc call to a Makefile | ||
| 48 | |||
| 49 | Example (in Makefile.PL): | ||
| 50 | |||
| 51 | name 'My-Schema'; | ||
| 52 | all_from 'lib/My/Schema.pm'; | ||
| 53 | author 'Foo Bar'; | ||
| 54 | |||
| 55 | dbicx_autodoc('doc'); # use name() or module_name() as Schema package | ||
| 56 | # or | ||
| 57 | dbix_autodoc('doc','My::Schema'); # better be in lib/ | ||
| 58 | # or | ||
| 59 | dbix_autodoc({ | ||
| 60 | output => 'doc', | ||
| 61 | schema => 'My::Schema' | ||
| 62 | }); | ||
| 63 | |||
| 64 | This would run DBICx::AutoDoc for My::Schema and store documents in <module-directory>/doc. | ||
| 65 | |||
| 66 | =cut | ||
| 67 | |||
| 68 | sub dbicx_autodoc { | ||
| 69 | my $self = shift; | ||
| 70 | |||
| 71 | return unless $Module::Install::AUTHOR; | ||
| 72 | |||
| 73 | die "First argrument to 'dbicx_autodoc' must be either an output directory or a HASH ref" | ||
| 74 | unless ref($_[0]) eq 'HASH' or !ref($_[0]); | ||
| 75 | |||
| 76 | # if our fix argrument (after self) is a hash ref use that as | ||
| 77 | # our constructor for DBICx::AutoDoc else use our first argrument | ||
| 78 | # as our output directory for DBICx::Schema | ||
| 79 | # if our first argrument is not a hash and is not defined | ||
| 80 | # use our module_name or name from Module::Install after | ||
| 81 | # replacing '-' with '::' | ||
| 82 | |||
| 83 | my %args = ref $_[0] eq 'HASH'? %{$_[0]} : ( | ||
| 84 | schema => defined $_[1]? $_[1] : $self->_get_fixed_module(), | ||
| 85 | output => $_[0] | ||
| 86 | ); | ||
| 87 | |||
| 88 | $SCHEMA = $args{schema}; | ||
| 89 | $AUTODOC_OUTPUT = $args{$output}; | ||
| 90 | |||
| 91 | my $m = $self->mk_makecmds(\%args); | ||
| 92 | return $self->postamble($m); | ||
| 93 | } | ||
| 94 | |||
| 95 | =head2 mk_makecmds | ||
| 96 | |||
| 97 | Generates our our Makefile statements | ||
| 98 | |||
| 99 | =cut | ||
| 100 | |||
| 101 | sub mk_makecmds { | ||
| 102 | my $self = shift; | ||
| 103 | my $hash = shift; | ||
| 104 | |||
| 105 | $self->_ck_hash($hash); | ||
| 106 | |||
| 107 | return qq/autodoc :: all\n/. | ||
| 108 | qq/\t\$(PERLRUN) -I\$(INST_LIB) -MDBICx::AutoDoc -e '/. | ||
| 109 | $self->gen_dbicxautodoc($hash). | ||
| 110 | qq/'\n\ndistclean :: autodoc_clean\n\n/. | ||
| 111 | qq/autodoc_clean:\n\t\$(RM_RF) /.$hash->{output}. | ||
| 112 | qq/\n\n/; | ||
| 113 | } | ||
| 114 | |||
| 115 | =head2 gen_dbicxautodoc | ||
| 116 | |||
| 117 | Generates or DBICx::AutoDoc command line call | ||
| 118 | |||
| 119 | =cut | ||
| 120 | |||
| 121 | sub gen_dbicxautodoc { | ||
| 122 | my $self = shift; | ||
| 123 | my $hash = shift; | ||
| 124 | |||
| 125 | $self->_ck_hash($hash); | ||
| 126 | |||
| 127 | my $str = Data::Dump::dump($hash); | ||
| 128 | my $ret = q/my $$h=/.$str.q/;DBICx::AutoDoc->new(%{$$h})->fill_all_templates()/; | ||
| 129 | |||
| 130 | return $ret; | ||
| 131 | } | ||
| 132 | |||
| 133 | sub _ck_hash { | ||
| 134 | my $self = shift; | ||
| 135 | my $hash = shift; | ||
| 136 | |||
| 137 | die "Recieved an ".ref($hash)." ref when we expected a HASH ref" | ||
| 138 | unless ref($hash) eq 'HASH'; | ||
| 139 | |||
| 140 | } | ||
| 141 | |||
| 142 | sub _get_fixed_module { | ||
| 143 | my $self = shift; | ||
| 144 | return join('::',split(/-/, | ||
| 145 | ($self->module_name? $self->module_name : $self->name ) | ||
| 146 | )); | ||
| 147 | } | ||
| 148 | |||
| 149 | |||
| 150 | =head1 AUTHOR | ||
| 151 | |||
| 152 | Jason M. Mills, C<< <jmmills at cpan.org> >> | ||
| 153 | |||
| 154 | =head1 BUGS | ||
| 155 | |||
| 156 | B<Warning!>, I have yet to write a "proper" unit test for the Makefile preamble output. I do use this module for my internal db libs and haven't found a problem yet. If someone wanted to contribute a good unit test it would be greatly appreciated. | ||
| 157 | |||
| 158 | Please report any bugs or feature requests to C<bug-module-install-dbicx-autodoc at rt.cpan.org>, or through | ||
| 159 | the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Install-DBICx-AutoDoc>. I will be notified, and then you'll | ||
| 160 | automatically be notified of progress on your bug as I make changes. | ||
| 161 | |||
| 162 | =head1 SUPPORT | ||
| 163 | |||
| 164 | You can find documentation for this module with the perldoc command. | ||
| 165 | |||
| 166 | perldoc Module::Install::DBICx::AutoDoc | ||
| 167 | |||
| 168 | |||
| 169 | You can also look for information at: | ||
| 170 | |||
| 171 | =over 4 | ||
| 172 | |||
| 173 | =item * RT: CPAN's request tracker | ||
| 174 | |||
| 175 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Install-DBICx-AutoDoc> | ||
| 176 | |||
| 177 | =item * AnnoCPAN: Annotated CPAN documentation | ||
| 178 | |||
| 179 | L<http://annocpan.org/dist/Module-Install-DBICx-AutoDoc> | ||
| 180 | |||
| 181 | =item * CPAN Ratings | ||
| 182 | |||
| 183 | L<http://cpanratings.perl.org/d/Module-Install-DBICx-AutoDoc> | ||
| 184 | |||
| 185 | =item * Search CPAN | ||
| 186 | |||
| 187 | L<http://search.cpan.org/dist/Module-Install-DBICx-AutoDoc> | ||
| 188 | |||
| 189 | =back | ||
| 190 | |||
| 191 | =head1 SEE ALSO | ||
| 192 | |||
| 193 | Module::Install, Module::Install::AutoManifest | ||
| 194 | |||
| 195 | =head1 COPYRIGHT & LICENSE | ||
| 196 | |||
| 197 | Copyright 2008 Jason M. Mills | ||
| 198 | |||
| 199 | This program is free software; you can redistribute it and/or modify it | ||
| 200 | under the same terms as Perl itself. | ||
| 201 | |||
| 202 | =cut | ||
| 203 | |||
| 204 | 1; # End of Module::Install::DBICx::AutoDoc | ||
| 205 |