Permalink
Browse files

More documentation around the DDG::Meta:: classes and DDG::HasShareDi…

…r role, refactoring DDG::Meta::ZeroClickInfo to use Package::Stash
  • Loading branch information...
1 parent db578d5 commit 1e7acf1bf1379ee53b84ef0c07035fc7df6e456d @Getty Getty committed Jul 9, 2012
Showing with 91 additions and 36 deletions.
  1. +3 −4 lib/DDG/HasShareDir.pm
  2. +19 −9 lib/DDG/Meta/RequestHandler.pm
  3. +46 −1 lib/DDG/Meta/ShareDir.pm
  4. +23 −22 lib/DDG/Meta/ZeroClickInfo.pm
View
@@ -16,14 +16,13 @@ informations. A class which has no sharedir is not allowed to carry this role.
The class using this role must implement B<module_share_dir> and B<share>.
B<module_share_dir> must return the path to the sharedir inside the repo,
-like:
-
- share/goodie/public_dns
+like B<share/goodie/public_dns>.
B<share> must give back a L<Path::Class::Dir> of the share directory if its
called without parameter. If a parameter is given it must give back
L<Path::Class::File> or L<Path::Class::Dir> of the corresponding file in the
-sharedir that is given as parameter.
+sharedir that is given as parameter. Checkout L<DDG::Meta::ShareDir/share> for
+information about usage of this function.
For more information about the sharedir see L<DDG::Meta::ShareDir>.
@@ -40,6 +40,16 @@ my @request_array_attributes = qw(
my $default_handler = 'query_raw';
+=method apply_keywords
+
+This function installs the L</handle> keyword. It requires for this the target
+package name, a result handler for handling the results of the plugins and
+optional a role which is applied after installing the keyword. This function
+is used in L<DDG::Meta> as part of all the meta for L<DDG::Goodie> and
+L<DDG::Spice>.
+
+=cut
+
sub apply_keywords {
my ( $class, $target, $result_handler, $role ) = @_;
@@ -67,6 +77,13 @@ get B<query_raw> on B<$_> and the array of the attribute on B<@_>.
If you dont give any keyword and just give a coderef, then B<query_raw> is
taken as keyword for the attribute.
+L<DDG::Block::Regexp> based plugins can use B<matches> to get the matches of
+the regexp as parameter on B<@_>.
+
+L<DDG::Block::Words> can use B<remainder> and B<remainder_lc> which gives back
+the parts of the query which are not hit by the trigger of the plugin. It is
+the most used handler.
+
The following keywords can be used by all plugins, cause they are based on the
L<DDG::Request> itself:
@@ -86,19 +103,12 @@ B<$req> which is set to the current L<DDG::Request> for the call to the
coderef of the handler.
You also get B<$loc> and B<$lang> which are always L<DDG::Location> and
-L<DDG::Language> objects, even if the L<DDG::Request> had none. If this case
-is, then all functions give back empty values of the objects. This way you
+L<DDG::Language> objects, even if the L<DDG::Request> had none. Given this
+case, then all functions give back empty values of the objects. This way you
can directly work with those variable without getting error messages for
accessing functions which are not there. To find out if there is a location
or language at all you can use B<$has_loc> and B<$has_lang>.
-L<DDG::Block::Regexp> based plugins can use B<matches> to get the matches of
-the regexp as parameter on B<@_>.
-
-L<DDG::Block::Words> can use B<remainder> and B<remainder_lc> which gives back
-the parts of the query which are not hit by the trigger of the plugin. It is
-the most used handler.
-
=cut
$stash->add_symbol('&handle',sub {
View
@@ -1,4 +1,5 @@
package DDG::Meta::ShareDir;
+# ABSTRACT: Installing functions for easy access to the module sharedir
use strict;
use warnings;
@@ -10,8 +11,29 @@ use File::ShareDir ':ALL';
require Moo::Role;
+=head1 DESCRIPTION
+
+This package installs the function required for using a sharedir and also
+provides the function L<share> for easy access to it.
+
+B<Warning>: This function only installs its function when there is a sharedir
+at the proper directory inside the repository, else it will fail. You cant
+define that directory for yourself, the complete concept requires staying to
+the convention, see L</module_share_dir>.
+
+=cut
+
my %applied;
+=method apply_keywords
+
+Uses a given classname to install the described keywords.
+
+It also adds the role L<DDG::HasShareDir> to the target classname if the
+class has a sharedir.
+
+=cut
+
sub apply_keywords {
my ( $class, $target ) = @_;
@@ -81,14 +103,37 @@ sub apply_keywords {
if ($share) {
my $stash = Package::Stash->new($target);
- $stash->add_symbol('&module_share_dir', sub { $share_path });
+
+=keyword share
+
+This function gives direct access to sharedir content. For example with
+
+ my $file = share('somefile.txt');
+
+you will get a L<Path::Class::File> object of this specific file inside
+your sharedir. It works in development and inside the live system after
+installation of the module.
+
+=cut
+
$stash->add_symbol('&share', sub {
@_ ? -d dir($share,@_)
? $share->subdir(@_)
: $share->file(@_)
: $share
});
+=keyword module_share_dir
+
+This function gets installed as part of the requirements a sharedir must
+provide. It gives back the path inside the repository where the sharedir
+of this module is placed. B<DDG::Spice::TestTest> gets to
+B<share/spice/test_test>.
+
+=cut
+
+ $stash->add_symbol('&module_share_dir', sub { $share_path });
+
#
# apply role
#
@@ -4,6 +4,7 @@ use strict;
use warnings;
use Carp;
use DDG::ZeroClickInfo;
+use Package::Stash;
sub zeroclickinfo_attributes {qw(
abstract
@@ -44,31 +45,31 @@ sub apply_keywords {
shift @parts;
shift @parts;
my $answer_type = lc(join(' ',@parts));
+
+ my $stash = Package::Stash->new($target);
- {
- my %zci_params = (
- answer_type => $answer_type,
- );
- no strict "refs";
+ my %zci_params = (
+ answer_type => $answer_type,
+ );
+
+ $stash->add_symbol('&zci_new', sub {
+ shift;
+ DDG::ZeroClickInfo->new( %zci_params, ref $_[0] eq 'HASH' ? %{$_[0]} : @_ );
+ });
- *{"${target}::zci_new"} = sub {
- shift;
- DDG::ZeroClickInfo->new( %zci_params, ref $_[0] eq 'HASH' ? %{$_[0]} : @_ );
- };
- *{"${target}::zci"} = sub {
- if (ref $_[0] eq 'HASH') {
- for (keys %{$_[0]}) {
- $zci_params{check_zeroclickinfo_key($_)} = $_[0]->{$_};
- }
- } else {
- while (@_) {
- my $key = shift;
- my $value = shift;
- $zci_params{check_zeroclickinfo_key($key)} = $value;
- }
+ $stash->add_symbol('&zci', sub {
+ if (ref $_[0] eq 'HASH') {
+ for (keys %{$_[0]}) {
+ $zci_params{check_zeroclickinfo_key($_)} = $_[0]->{$_};
}
- };
- }
+ } else {
+ while (@_) {
+ my $key = shift;
+ my $value = shift;
+ $zci_params{check_zeroclickinfo_key($key)} = $value;
+ }
+ }
+ });
}

0 comments on commit 1e7acf1

Please sign in to comment.