rt/lib/RT/Interface/REST.pm

   1 # BEGIN BPS TAGGED BLOCK {{{
   2 #
   3 # COPYRIGHT:
   4 #
   5 # This software is Copyright (c) 1996-2007 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., 51 Franklin Street, Fifth Floor, Boston, MA
  26 # 02110-1301 or visit their web page on the internet at
  27 # http://www.gnu.org/copyleft/gpl.html.
  28 #
  29 #
  30 # CONTRIBUTION SUBMISSION POLICY:
  31 #
  32 # (The following paragraph is not intended to limit the rights granted
  33 # to you to modify and distribute this software under the terms of
  34 # the GNU General Public License and is only of importance to you if
  35 # you choose to contribute your changes and enhancements to the
  36 # community by submitting them to Best Practical Solutions, LLC.)
  37 #
  38 # By intentionally submitting any modifications, corrections or
  39 # derivatives to this work, or any other work intended for use with
  40 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
  41 # you are the copyright holder for those contributions and you grant
  42 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
  43 # royalty-free, perpetual, license to use, copy, create derivative
  44 # works based on those contributions, and sublicense and distribute
  45 # those contributions and any derivatives thereof.
  46 #
  47 # END BPS TAGGED BLOCK }}}
  48 # lib/RT/Interface/REST.pm
  49 #
  50
  51 package RT::Interface::REST;
  52 use strict;
  53 use RT;
  54
  55 BEGIN {
  56     use Exporter ();
  57     use vars qw($VERSION @ISA @EXPORT);
  58
  59     $VERSION = do { my @r = (q$Revision: 1.1.1.4 $ =~ /\d+/g); sprintf "%d."."%02d"x$#r, @r };
  60
  61     @ISA = qw(Exporter);
  62     @EXPORT = qw(expand_list form_parse form_compose vpush vsplit);
  63 }
  64
  65 my $field = '(?i:[a-z][a-z0-9_-]*|C(?:ustom)?F(?:ield)?-[a-z0-9_ -]+)';
  66
  67 # WARN: this code is duplicated in bin/rt.in,
  68 # change both functions at once
  69 sub expand_list {
  70     my ($list) = @_;
  71
  72     my @elts;
  73     foreach (split /,/, $list) {
  74         push @elts, /^(\d+)-(\d+)$/? ($1..$2): $_;
  75     }
  76
  77     return map $_->[0], # schwartzian transform
  78         sort {
  79             defined $a->[1] && defined $b->[1]?
  80                 # both numbers
  81                 $a->[1] <=> $b->[1]
  82                 :!defined $a->[1] && !defined $b->[1]?
  83                     # both letters
  84                     $a->[2] cmp $b->[2]
  85                     # mix, number must be first
  86                     :defined $a->[1]? -1: 1
  87         }
  88         map [ $_, (defined( /^(\d+)$/ )? $1: undef), lc($_) ],
  89         @elts;
  90 }
  91
  92 # Returns a reference to an array of parsed forms.
  93 sub form_parse {
  94     my $state = 0;
  95     my @forms = ();
  96     my @lines = split /\n/, $_[0];
  97     my ($c, $o, $k, $e) = ("", [], {}, "");
  98
  99     LINE:
 100     while (@lines) {
 101         my $line = shift @lines;
 102
 103         next LINE if $line eq '';
 104
 105         if ($line eq '--') {
 106             # We reached the end of one form. We'll ignore it if it was
 107             # empty, and store it otherwise, errors and all.
 108             if ($e || $c || @$o) {
 109                 push @forms, [ $c, $o, $k, $e ];
 110                 $c = ""; $o = []; $k = {}; $e = "";
 111             }
 112             $state = 0;
 113         }
 114         elsif ($state != -1) {
 115             if ($state == 0 && $line =~ /^#/) {
 116                 # Read an optional block of comments (only) at the start
 117                 # of the form.
 118                 $state = 1;
 119                 $c = $line;
 120                 while (@lines && $lines[0] =~ /^#/) {
 121                     $c .= "\n".shift @lines;
 122                 }
 123                 $c .= "\n";
 124             }
 125             elsif ($state <= 1 && $line =~ /^($field):(?:\s+(.*))?$/) {
 126                 # Read a field: value specification.
 127                 my $f  = $1;
 128                 my @v  = ($2 || ());
 129
 130                 # Read continuation lines, if any.
 131                 while (@lines && ($lines[0] eq '' || $lines[0] =~ /^\s+/)) {
 132                     push @v, shift @lines;
 133                 }
 134                 pop @v while (@v && $v[-1] eq '');
 135
 136                 # Strip longest common leading indent from text.
 137                 my ($ws, $ls) = ("");
 138                 foreach $ls (map {/^(\s+)/} @v[1..$#v]) {
 139                     $ws = $ls if (!$ws || length($ls) < length($ws));
 140                 }
 141                 s/^$ws// foreach @v;
 142
 143                 push(@$o, $f) unless exists $k->{$f};
 144                 vpush($k, $f, join("\n", @v));
 145
 146                 $state = 1;
 147             }
 148             elsif ($line !~ /^#/) {
 149                 # We've found a syntax error, so we'll reconstruct the
 150                 # form parsed thus far, and add an error marker. (>>)
 151                 $state = -1;
 152                 $e = form_compose([[ "", $o, $k, "" ]]);
 153                 $e.= $line =~ /^>>/ ? "$line\n" : ">> $line\n";
 154             }
 155         }
 156         else {
 157             # We saw a syntax error earlier, so we'll accumulate the
 158             # contents of this form until the end.
 159             $e .= "$line\n";
 160         }
 161     }
 162     push(@forms, [ $c, $o, $k, $e ]) if ($e || $c || @$o);
 163
 164     my $l;
 165     foreach $l (keys %$k) {
 166         $k->{$l} = vsplit($k->{$l}) if (ref $k->{$l} eq 'ARRAY');
 167     }
 168
 169     return \@forms;
 170 }
 171
 172 # Returns text representing a set of forms.
 173 sub form_compose {
 174     my ($forms) = @_;
 175     my (@text, $form);
 176
 177     foreach $form (@$forms) {
 178         my ($c, $o, $k, $e) = @$form;
 179         my $text = "";
 180
 181         if ($c) {
 182             $c =~ s/\n*$/\n/;
 183             $text = "$c\n";
 184         }
 185         if ($e) {
 186             $text .= $e;
 187         }
 188         elsif ($o) {
 189             my (@lines, $key);
 190
 191             foreach $key (@$o) {
 192                 my ($line, $sp, $v);
 193                 my @values = (ref $k->{$key} eq 'ARRAY') ?
 194                                @{ $k->{$key} } :
 195                                   $k->{$key};
 196
 197                 $sp = " "x(length("$key: "));
 198                 $sp = " "x4 if length($sp) > 16;
 199
 200                 foreach $v (@values) {
 201                     if ($v =~ /\n/) {
 202                         $v =~ s/^/$sp/gm;
 203                         $v =~ s/^$sp//;
 204
 205                         if ($line) {
 206                             push @lines, "$line\n\n";
 207                             $line = "";
 208                         }
 209                         elsif (@lines && $lines[-1] !~ /\n\n$/) {
 210                             $lines[-1] .= "\n";
 211                         }
 212                         push @lines, "$key: $v\n\n";
 213                     }
 214                     elsif ($line &&
 215                            length($line)+length($v)-rindex($line, "\n") >= 70)
 216                     {
 217                         $line .= ",\n$sp$v";
 218                     }
 219                     else {
 220                         $line = $line ? "$line, $v" : "$key: $v";
 221                     }
 222                 }
 223
 224                 $line = "$key:" unless @values;
 225                 if ($line) {
 226                     if ($line =~ /\n/) {
 227                         if (@lines && $lines[-1] !~ /\n\n$/) {
 228                             $lines[-1] .= "\n";
 229                         }
 230                         $line .= "\n";
 231                     }
 232                     push @lines, "$line\n";
 233                 }
 234             }
 235
 236             $text .= join "", @lines;
 237         }
 238         else {
 239             chomp $text;
 240         }
 241         push @text, $text;
 242     }
 243
 244     return join "\n--\n\n", @text;
 245 }
 246
 247 # Add a value to a (possibly multi-valued) hash key.
 248 sub vpush {
 249     my ($hash, $key, $val) = @_;
 250     my @val = ref $val eq 'ARRAY' ? @$val : $val;
 251
 252     if (exists $hash->{$key}) {
 253         unless (ref $hash->{$key} eq 'ARRAY') {
 254             my @v = $hash->{$key} ne '' ? $hash->{$key} : ();
 255             $hash->{$key} = \@v;
 256         }
 257         push @{ $hash->{$key} }, @val;
 258     }
 259     else {
 260         $hash->{$key} = $val;
 261     }
 262 }
 263
 264 # "Normalise" a hash key that's known to be multi-valued.
 265 sub vsplit {
 266     my ($val) = @_;
 267     my ($line, $word, @words);
 268
 269     foreach $line (map {split /\n/} (ref $val eq 'ARRAY') ? @$val : $val)
 270     {
 271         # XXX: This should become a real parser, à la Text::ParseWords.
 272         $line =~ s/^\s+//;
 273         $line =~ s/\s+$//;
 274         push @words, split /\s*,\s*/, $line;
 275     }
 276
 277     return \@words;
 278 }
 279
 280 1;
 281
 282 =head1 NAME
 283
 284   RT::Interface::REST - helper functions for the REST interface.
 285
 286 =head1 SYNOPSIS
 287
 288   Only the REST should use this module.