lib/Zeal.pm

   1 package Zeal;
   2
   3 use 5.014000;
   4 use strict;
   5 use warnings;
   6 use re '/s';
   7
   8 our $VERSION = '0.001001';
   9
  10 use File::Spec::Functions qw/catfile/;
  11
  12 use Zeal::Docset;
  13 use Zeal::Document;
  14
  15 sub new {
  16         my ($class, $path) = @_;
  17         $path //= $ENV{ZEAL_PATH};
  18         my $self = bless {sets => {}}, $class;
  19         if ($path) {
  20                 $self->add($_) for split /:/, $path;
  21         }
  22         $self
  23 }
  24
  25 sub add {
  26         my ($self, $path) = @_;
  27         return unless -d $path;
  28         if ($path =~ /[.]docset$/) {
  29                 my $ds = Zeal::Docset->new($path);
  30                 $self->{sets}{$ds->family} //= [];
  31                 push @{$self->{sets}{$ds->family}}, $ds;
  32         } else {
  33                 my $dir;
  34                 opendir $dir, $path;
  35                 my @entries = grep { !/^[.]{1,2}$/ } readdir $dir;
  36                 closedir $dir;
  37                 $self->add(catfile $path, $_) for @entries
  38         }
  39 }
  40
  41 sub sets {
  42         my ($self, $family) = @_;
  43         return map { @$_ } values %{$self->{sets}} unless $family;
  44         die "No docsets in family '$family'\n" unless $self->{sets}{$family};
  45         @{$self->{sets}{$family}}
  46 }
  47
  48 sub query {
  49         my ($self, $query, $family) = @_;
  50         ($family, $query) = split /:/, $query, 2 if !$family && $query =~ /^\w+:[^:]/;
  51         my @res = map { $_->query($query) } $self->sets($family);
  52         wantarray ? @res : $res[0]
  53 }
  54
  55 1;
  56 __END__
  57
  58 =encoding utf-8
  59
  60 =head1 NAME
  61
  62 Zeal - Read and query Dash/Zeal docsets
  63
  64 =head1 SYNOPSIS
  65
  66   use Zeal;
  67   my $zeal = Zeal->new("/home/mgv/docsets/:/home/mgv/something.docset");
  68   $zeal->add('/home/mgv/somethingelse.docset'); # Add another docset
  69   $zeal->add('/home/mgv/moredocsets/');         # Add a directory containing docsets
  70
  71   my $doc = $zeal->query('length');             # Documentation for 'length' in all docsets
  72   my @docs = $zeal->query('Test::%', 'perl');   # Documentation for all Test:: perl modules
  73   @docs = $zeal->query('perl:Test::%);          # Alternative syntax
  74
  75 =head1 DESCRIPTION
  76
  77 Dash is an offline API documentation browser. Zeal.pm is a module for
  78 reading and querying Dash documentation sets.
  79
  80 This module queries multiple docsets. If you only have one docset, you
  81 should use the L<Zeal::Docset> module directly.
  82
  83 Available methods:
  84
  85 =over
  86
  87 =item Zeal->B<new>([I<$path>])
  88
  89 Create a new Zeal object. I<$path> is an optional colon delimited
  90 string for initializing the object. Each of its components is
  91 recursively scanned for docsets (and can also be a docset itself). If
  92 I<$path> is not provided, the value of I<$ENV{ZEAL_PATH}> (if defined)
  93 is used instead.
  94
  95 =item $zeal->B<add>(I<$path>)
  96
  97 Recursively scan a path for docsets, adding them to this object.
  98
  99 =item $zeal->B<sets>([I<$family>])
 100
 101 Return a list of docsets (L<Zeal::Docset> objects) in the given
 102 family, or in all families if I<$family> is not provided.
 103
 104 =item $zeal->B<query>(I<"$family:$query">)
 105
 106 =item $zeal->B<query>(I<$query>, [I<$family>])
 107
 108 Return a list of documents (L<Zeal::Document> objects) matching a
 109 query, optionally restricted to a family. In scalar context only one
 110 such document is returned. I<$query> is a SQL LIKE condition.
 111
 112 =back
 113
 114 =head1 SEE ALSO
 115
 116 L<http://kapeli.com/dash>, L<http://zealdocs.org>
 117
 118 =head1 AUTHOR
 119
 120 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 121
 122 =head1 COPYRIGHT AND LICENSE
 123
 124 Copyright (C) 2014-2015 by Marius Gavrilescu
 125
 126 This library is free software; you can redistribute it and/or modify
 127 it under the same terms as Perl itself, either Perl version 5.20.1 or,
 128 at your option, any later version of Perl 5 you may have available.
 129
 130
 131 =cut