vcs.maemo.org Git - maemian/blob - nokia-lintian/lib/Lintian/Data.pm

   1 # -*- perl -*-
   2 # Lintian::Data -- interface to query lists of keywords
   3
   4 # Copyright (C) 2008 Russ Allbery
   5 #
   6 # This program is free software; you can redistribute it and/or modify it
   7 # under the terms of the GNU General Public License as published by the Free
   8 # Software Foundation; either version 2 of the License, or (at your option)
   9 # any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful, but WITHOUT
  12 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  14 # more details.
  15 #
  16 # You should have received a copy of the GNU General Public License along with
  17 # this program.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 package Lintian::Data;
  20 use strict;
  21
  22 use Carp qw(croak);
  23
  24 # The constructor loads a list into a hash in %data, which is private to this
  25 # module.  Use %data as a cache to avoid loading the same list more than once
  26 # (which means lintian doesn't support having the list change over the life of
  27 # the proces.  The returned object knows what list, stored in %data, it is
  28 # supposed to act on.
  29 {
  30     my %data;
  31     sub new {
  32         my ($class, $type) = @_;
  33         croak('no data type specified') unless $type;
  34         unless (exists $data{$type}) {
  35             my $dir = $ENV{LINTIAN_ROOT} . '/data';
  36             open(LIST, '<', "$dir/$type")
  37                 or croak("unknown data type $type");
  38             local ($_, $.);
  39             while (<LIST>) {
  40                 chomp;
  41                 s/^\s+//;
  42                 next if /^\#/;
  43                 next if /^$/;
  44                 $data{$type}{$_} = 1;
  45             }
  46         }
  47         my $self = { data => $data{$type} };
  48         bless($self, $class);
  49         return $self;
  50     }
  51 }
  52
  53 # Query a data object for whether a particular keyword is valid.
  54 sub known {
  55     my ($self, $keyword) = @_;
  56     return (exists $self->{data}{$keyword}) ? 1 : undef;
  57 }
  58
  59 =head1 NAME
  60
  61 Lintian::Data - Lintian interface to query lists of keywords
  62
  63 =head1 SYNOPSIS
  64
  65     my $list = Lintian::Data->new('type');
  66     if ($list->known($keyword)) {
  67         # do something ...
  68     }
  69
  70 =head1 DESCRIPTION
  71
  72 Lintian::Data provides a way of loading a list of keywords from a file in
  73 the Lintian root and then querying that list.  The lists are stored in the
  74 F<data> directory of the Lintian root and consist of one keyword per line.
  75 Blank lines and lines beginning with C<#> are ignored.  Leading and
  76 trailing whitespace is stripped; other than that, keywords are taken
  77 verbatim as they are listed in the file and may include spaces.
  78
  79 This module allows lists such as menu sections, doc-base sections,
  80 obsolete packages, package fields, and so forth to be stored in simple,
  81 easily editable files.
  82
  83 =head1 CLASS METHODS
  84
  85 =over 4
  86
  87 =item new(TYPE)
  88
  89 Creates a new Lintian::Data object for the given TYPE.  TYPE is a partial
  90 path relative to the F<data> directory and should correspond to a file in
  91 that directory.  The contents of that file will be loaded into memory and
  92 returned as part of the newly created object.  On error, new() throws an
  93 exception.
  94
  95 A given file will only be loaded once.  If new() is called again with the
  96 same TYPE argument, the data previously loaded will be reused, avoiding
  97 multiple file reads.
  98
  99 =back
 100
 101 =head1 INSTANCE METHODS
 102
 103 =over 4
 104
 105 =item known(KEYWORD)
 106
 107 Returns true if KEYWORD was listed in the data file represented by this
 108 Lintian::Data instance and false otherwise.
 109
 110 =back
 111
 112 =head1 DIAGNOSTICS
 113
 114 =over 4
 115
 116 =item no data type specified
 117
 118 new() was called without a TYPE argument.
 119
 120 =item unknown data type %s
 121
 122 The TYPE argument to new() did not correspond to a file in the F<data>
 123 directory of the Lintian root.
 124
 125 =back
 126
 127 =head1 FILES
 128
 129 =over 4
 130
 131 =item LINTIAN_ROOT/data
 132
 133 The files loaded by this module must be located in this directory.
 134 Relative paths containing a C</> are permitted, so files may be organized
 135 in subdirectories in this directory.
 136
 137 =back
 138
 139 =head1 ENVIRONMENT
 140
 141 =over 4
 142
 143 =item LINTIAN_ROOT
 144
 145 This variable must be set to Lintian's root directory (normally
 146 F</usr/share/lintian> when Lintian is installed as a Debian package).  The
 147 B<lintian> program normally takes care of doing this.  This module doesn't
 148 care about the contents of this directory other than expecting the F<data>
 149 subdirectory of this directory to contain its files.
 150
 151 =back
 152
 153 =head1 AUTHOR
 154
 155 Originally written by Russ Allbery <rra@debian.org> for Lintian.
 156
 157 =head1 SEE ALSO
 158
 159 lintian(1)
 160
 161 =cut
 162
 163 1;
 164
 165 # Local Variables:
 166 # indent-tabs-mode: nil
 167 # cperl-indent-level: 4
 168 # End:
 169 # vim: syntax=perl sw=4 sts=4 ts=4 et shiftround