perllib/General/Parse.pm

   1 # Copyright (c) 2002-2009, Mikhael Goikhman
   2 #
   3 # This program is free software; you can redistribute it and/or modify
   4 # it under the terms of the GNU General Public License as published by
   5 # the Free Software Foundation; either version 2 of the License, or
   6 # (at your option) any later version.
   7 #
   8 # This program is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 # GNU General Public License for more details.
  12 #
  13 # You should have received a copy of the GNU General Public License
  14 # along with this program; if not, write to the Free Software
  15 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  16
  17 package General::Parse;
  18 use strict;
  19
  20 use vars qw(@ISA @EXPORT);
  21 require Exporter;
  22 @ISA = qw(Exporter);
  23 @EXPORT = qw(
  24         get_token cut_token get_tokens cut_tokens eqi nei
  25 );
  26
  27 # currently backslashes are ignored and this is a bit buggy
  28 sub get_token ($) {
  29         my $line = shift;
  30         my $token;
  31
  32         $line =~ s/^\s+//;
  33         my $quote = '\s';
  34         $quote = substr($line, 0, 1) if $line =~ /^["'`]/;
  35
  36         $line =~ s/^$quote//;
  37         if ($line =~ /^(.*?)$quote\s*(.*)$/) {
  38                 $token = $1;
  39                 $line = $2;
  40         } elsif ($line eq "") {
  41                 $token = undef;
  42                 $line = "";
  43         } else {
  44                 $token = $line;
  45                 $line = "";
  46         }
  47         return wantarray ? ($token, $line) : $token;
  48 }
  49
  50 # returns the next quoted token, modifies the parameter (ref to line)
  51 sub cut_token ($) {
  52         my $line_ref = shift;
  53         my ($token, $rest) = get_token($$line_ref);
  54         $$line_ref = $rest;
  55         return $token;
  56 }
  57
  58 sub cut_tokens ($$) {
  59         my $line_ref = shift;
  60         my $limit = shift;
  61         my @tokens = ();
  62
  63         $$line_ref =~ s/^\s+//;
  64         while ($$line_ref ne "" && $limit-- > 0) {
  65                 push @tokens, cut_token($line_ref);
  66         }
  67         return wantarray ? @tokens : \@tokens;
  68 }
  69
  70 sub get_tokens ($;$) {
  71         my $line = shift;
  72         my $limit = shift || 1000;
  73
  74         return cut_tokens(\$line, $limit);
  75 }
  76
  77 sub eqi ($$) {
  78         my ($a, $b) = @_;
  79         return lc($a) eq lc($b);
  80 }
  81
  82 sub nei ($$) {
  83         my ($a, $b) = @_;
  84         return lc($a) ne lc($b);
  85 }
  86
  87 # ----------------------------------------------------------------------------
  88
  89 =head1 NAME
  90
  91 General::Parse - parsing functions
  92
  93 =head1 SYNOPSIS
  94
  95   use General::Parse;
  96
  97   my $string = q{Some "not very long" string of 6 tokens.};
  98   my $token1 = cut_token(\$string);          # $token1 = "Some";
  99   my ($token2, $token3) = cut_tokens(\$string, 2);
 100   my @subtokens = get_tokens($token2);       # ("not", "very", "long")
 101   my $subtoken1 = get_token($token2);        # the same as $subtokens[0]
 102   my $ending_array_ref = get_tokens($string);  # ["of", "6", "tokens."]
 103
 104 =head1 DESCRIPTION
 105
 106 This package may be used for parsing a string into tokens (quoted words).
 107
 108 =head1 FUNCTIONS
 109
 110
 111 =head2 get_token
 112
 113 =over 4
 114
 115 =item description
 116
 117 Returns the first token of the given string without changing the string itself.
 118
 119 If the string is empty or consists of only spaces the returned token is undef.
 120
 121 If the caller expects a scalar - the token is returned. If it expects an
 122 array - 2 values returned, the token and the rest of the string.
 123
 124 =item parameters
 125
 126 String (scalar) to be parsed.
 127
 128 =item returns
 129
 130 Token (scalar).
 131 Or, in array context, array of 2 scalars: token and the rest of string.
 132
 133 =back
 134
 135
 136 =head2 cut_token
 137
 138 =over 4
 139
 140 =item description
 141
 142 Returns the first token of the given string, the input string is cut to
 143 contain tokens starting from the second one.
 144
 145 If the string is empty or consists of only spaces the returned token is undef
 146 and the string is changed to an empty string.
 147
 148 =item parameters
 149
 150 String (scalar) to be parsed.
 151
 152 =item returns
 153
 154 Token (scalar).
 155
 156 =back
 157
 158
 159 =head2 get_tokens
 160
 161 =over 4
 162
 163 =item description
 164
 165 Returns all or the requested number of tokens of the given string without
 166 changing the string itself.
 167
 168 The returned array may contain less tokens than requested if the string
 169 is too short. Particularly, the returned array is empty if the string is empty
 170 or consists of only spaces.
 171
 172 If the caller expects a scalar - a reference to the token array is returned.
 173 If it expects an array - the token array is returned.
 174
 175 =item parameters
 176
 177 String (scalar) to be parsed, and optional limit (integer) for number of
 178 returned tokens.
 179
 180 =item returns
 181
 182 Tokens (array of scalars or array ref of scalars depending on context).
 183
 184 =back
 185
 186
 187 =head2 cut_tokens
 188
 189 =over 4
 190
 191 =item description
 192
 193 Returns the requested number of tokens of the given string, the string is cut
 194 to contain the tokens starting from the first non returned token.
 195
 196 The returned array may contain less tokens than requested if the string
 197 is too short. Particularly, the returned array is empty if the string is empty
 198 or consists of only spaces.
 199
 200 If the caller expects a scalar - a reference to the token array is returned.
 201 If it expects an array - the token array is returned.
 202
 203 =item parameters
 204
 205 String (scalar) to be parsed, and limit (integer) for number of
 206 returned tokens.
 207
 208 =item returns
 209
 210 Tokens (array of scalars or array ref of scalars depending on context).
 211
 212 =back
 213
 214
 215 =head2 eqi
 216
 217 =over 4
 218
 219 =item description
 220
 221 Similar to B<eq>, but case-insensitive, gets 2 strings, returns boolean.
 222
 223 =back
 224
 225
 226 =head2 nei
 227
 228 =over 4
 229
 230 =item description
 231
 232 Similar to B<ne>, but case-insensitive, gets 2 strings, returns boolean.
 233
 234 =back
 235
 236
 237 =head1 AUTHOR
 238
 239 Mikhael Goikhman <migo@homemail.com>
 240
 241 =cut
 242 # ============================================================================
 243
 244 1;