]> iEval git - zeal.git/blob - lib/Zeal.pm
1ba955eeea38843c4be8e040f3dc089b212a71b5
[zeal.git] / 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.000_003';
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
This page took 0.056017 seconds and 3 git commands to generate.