rt/lib/RT/Interface/REST.pm

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