rt/lib/RT/Interface/REST.pm

   1 # BEGIN BPS TAGGED BLOCK {{{
   2 #
   3 # COPYRIGHT:
   4 #
   5 # This software is Copyright (c) 1996-2005 Best Practical Solutions, LLC
   6 #                                          <jesse@bestpractical.com>
   7 #
   8 # (Except where explicitly superseded by other copyright notices)
   9 #
  10 #
  11 # LICENSE:
  12 #
  13 # This work is made available to you under the terms of Version 2 of
  14 # the GNU General Public License. A copy of that license should have
  15 # been provided with this software, but in any event can be snarfed
  16 # from www.gnu.org.
  17 #
  18 # This work is distributed in the hope that it will be useful, but
  19 # WITHOUT ANY WARRANTY; without even the implied warranty of
  20 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21 # General Public License for more details.
  22 #
  23 # You should have received a copy of the GNU General Public License
  24 # along with this program; if not, write to the Free Software
  25 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  26 #
  27 #
  28 # CONTRIBUTION SUBMISSION POLICY:
  29 #
  30 # (The following paragraph is not intended to limit the rights granted
  31 # to you to modify and distribute this software under the terms of
  32 # the GNU General Public License and is only of importance to you if
  33 # you choose to contribute your changes and enhancements to the
  34 # community by submitting them to Best Practical Solutions, LLC.)
  35 #
  36 # By intentionally submitting any modifications, corrections or
  37 # derivatives to this work, or any other work intended for use with
  38 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
  39 # you are the copyright holder for those contributions and you grant
  40 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
  41 # royalty-free, perpetual, license to use, copy, create derivative
  42 # works based on those contributions, and sublicense and distribute
  43 # those contributions and any derivatives thereof.
  44 #
  45 # END BPS TAGGED BLOCK }}}
  46 # lib/RT/Interface/REST.pm
  47 #
  48
  49 package RT::Interface::REST;
  50 use strict;
  51 use RT;
  52
  53 BEGIN {
  54     use Exporter ();
  55     use vars qw($VERSION @ISA @EXPORT);
  56
  57     $VERSION = do { my @r = (q$Revision: 1.1.1.3 $ =~ /\d+/g); sprintf "%d."."%02d"x$#r, @r };
  58
  59     @ISA = qw(Exporter);
  60     @EXPORT = qw(expand_list form_parse form_compose vpush vsplit);
  61 }
  62
  63 my $field = '[a-zA-Z][a-zA-Z0-9_-]*';
  64
  65 sub expand_list {
  66     my ($list) = @_;
  67     my ($elt, @elts, %elts);
  68
  69     foreach $elt (split /,/, $list) {
  70         if ($elt =~ /^(\d+)-(\d+)$/) { push @elts, ($1..$2) }
  71         else                         { push @elts, $elt }
  72     }
  73
  74     @elts{@elts}=();
  75     return sort {$a<=>$b} keys %elts;
  76 }
  77
  78 # Returns a reference to an array of parsed forms.
  79 sub form_parse {
  80     my $state = 0;
  81     my @forms = ();
  82     my @lines = split /\n/, $_[0];
  83     my ($c, $o, $k, $e) = ("", [], {}, "");
  84
  85     LINE:
  86     while (@lines) {
  87         my $line = shift @lines;
  88
  89         next LINE if $line eq '';
  90
  91         if ($line eq '--') {
  92             # We reached the end of one form. We'll ignore it if it was
  93             # empty, and store it otherwise, errors and all.
  94             if ($e || $c || @$o) {
  95                 push @forms, [ $c, $o, $k, $e ];
  96                 $c = ""; $o = []; $k = {}; $e = "";
  97             }
  98             $state = 0;
  99         }
 100         elsif ($state != -1) {
 101             if ($state == 0 && $line =~ /^#/) {
 102                 # Read an optional block of comments (only) at the start
 103                 # of the form.
 104                 $state = 1;
 105                 $c = $line;
 106                 while (@lines && $lines[0] =~ /^#/) {
 107                     $c .= "\n".shift @lines;
 108                 }
 109                 $c .= "\n";
 110             }
 111             elsif ($state <= 1 && $line =~ /^($field):(?:\s+(.*))?$/) {
 112                 # Read a field: value specification.
 113                 my $f  = $1;
 114                 my @v  = ($2 || ());
 115
 116                 # Read continuation lines, if any.
 117                 while (@lines && ($lines[0] eq '' || $lines[0] =~ /^\s+/)) {
 118                     push @v, shift @lines;
 119                 }
 120                 pop @v while (@v && $v[-1] eq '');
 121
 122                 # Strip longest common leading indent from text.
 123                 my ($ws, $ls) = ("");
 124                 foreach $ls (map {/^(\s+)/} @v[1..$#v]) {
 125                     $ws = $ls if (!$ws || length($ls) < length($ws));
 126                 }
 127                 s/^$ws// foreach @v;
 128
 129                 push(@$o, $f) unless exists $k->{$f};
 130                 vpush($k, $f, join("\n", @v));
 131
 132                 $state = 1;
 133             }
 134             elsif ($line !~ /^#/) {
 135                 # We've found a syntax error, so we'll reconstruct the
 136                 # form parsed thus far, and add an error marker. (>>)
 137                 $state = -1;
 138                 $e = form_compose([[ "", $o, $k, "" ]]);
 139                 $e.= $line =~ /^>>/ ? "$line\n" : ">> $line\n";
 140             }
 141         }
 142         else {
 143             # We saw a syntax error earlier, so we'll accumulate the
 144             # contents of this form until the end.
 145             $e .= "$line\n";
 146         }
 147     }
 148     push(@forms, [ $c, $o, $k, $e ]) if ($e || $c || @$o);
 149
 150     my $l;
 151     foreach $l (keys %$k) {
 152         $k->{$l} = vsplit($k->{$l}) if (ref $k->{$l} eq 'ARRAY');
 153     }
 154
 155     return \@forms;
 156 }
 157
 158 # Returns text representing a set of forms.
 159 sub form_compose {
 160     my ($forms) = @_;
 161     my (@text, $form);
 162
 163     foreach $form (@$forms) {
 164         my ($c, $o, $k, $e) = @$form;
 165         my $text = "";
 166
 167         if ($c) {
 168             $c =~ s/\n*$/\n/;
 169             $text = "$c\n";
 170         }
 171         if ($e) {
 172             $text .= $e;
 173         }
 174         elsif ($o) {
 175             my (@lines, $key);
 176
 177             foreach $key (@$o) {
 178                 my ($line, $sp, $v);
 179                 my @values = (ref $k->{$key} eq 'ARRAY') ?
 180                                @{ $k->{$key} } :
 181                                   $k->{$key};
 182
 183                 $sp = " "x(length("$key: "));
 184                 $sp = " "x4 if length($sp) > 16;
 185
 186                 foreach $v (@values) {
 187                     if ($v =~ /\n/) {
 188                         $v =~ s/^/$sp/gm;
 189                         $v =~ s/^$sp//;
 190
 191                         if ($line) {
 192                             push @lines, "$line\n\n";
 193                             $line = "";
 194                         }
 195                         elsif (@lines && $lines[-1] !~ /\n\n$/) {
 196                             $lines[-1] .= "\n";
 197                         }
 198                         push @lines, "$key: $v\n\n";
 199                     }
 200                     elsif ($line &&
 201                            length($line)+length($v)-rindex($line, "\n") >= 70)
 202                     {
 203                         $line .= ",\n$sp$v";
 204                     }
 205                     else {
 206                         $line = $line ? "$line, $v" : "$key: $v";
 207                     }
 208                 }
 209
 210                 $line = "$key:" unless @values;
 211                 if ($line) {
 212                     if ($line =~ /\n/) {
 213                         if (@lines && $lines[-1] !~ /\n\n$/) {
 214                             $lines[-1] .= "\n";
 215                         }
 216                         $line .= "\n";
 217                     }
 218                     push @lines, "$line\n";
 219                 }
 220             }
 221
 222             $text .= join "", @lines;
 223         }
 224         else {
 225             chomp $text;
 226         }
 227         push @text, $text;
 228     }
 229
 230     return join "\n--\n\n", @text;
 231 }
 232
 233 # Add a value to a (possibly multi-valued) hash key.
 234 sub vpush {
 235     my ($hash, $key, $val) = @_;
 236     my @val = ref $val eq 'ARRAY' ? @$val : $val;
 237
 238     if (exists $hash->{$key}) {
 239         unless (ref $hash->{$key} eq 'ARRAY') {
 240             my @v = $hash->{$key} ne '' ? $hash->{$key} : ();
 241             $hash->{$key} = \@v;
 242         }
 243         push @{ $hash->{$key} }, @val;
 244     }
 245     else {
 246         $hash->{$key} = $val;
 247     }
 248 }
 249
 250 # "Normalise" a hash key that's known to be multi-valued.
 251 sub vsplit {
 252     my ($val) = @_;
 253     my ($line, $word, @words);
 254
 255     foreach $line (map {split /\n/} (ref $val eq 'ARRAY') ? @$val : $val)
 256     {
 257         # XXX: This should become a real parser, à la Text::ParseWords.
 258         $line =~ s/^\s+//;
 259         $line =~ s/\s+$//;
 260         push @words, split /\s*,\s*/, $line;
 261     }
 262
 263     return \@words;
 264 }
 265
 266 1;
 267
 268 =head1 NAME
 269
 270   RT::Interface::REST - helper functions for the REST interface.
 271
 272 =head1 SYNOPSIS
 273
 274   Only the REST should use this module.