1 # BEGIN BPS TAGGED BLOCK {{{
5 # This software is Copyright (c) 1996-2011 Best Practical Solutions, LLC
6 # <sales@bestpractical.com>
8 # (Except where explicitly superseded by other copyright notices)
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
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.
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/licenses/old-licenses/gpl-2.0.html.
30 # CONTRIBUTION SUBMISSION POLICY:
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.)
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.
47 # END BPS TAGGED BLOCK }}}
49 # lib/RT/Interface/REST.pm
52 package RT::Interface::REST;
59 use vars qw($VERSION @EXPORT);
61 $VERSION = do { my @r = (q$Revision: 1.1.1.10 $ =~ /\d+/g); sprintf "%d."."%02d"x$#r, @r };
63 @EXPORT = qw(expand_list form_parse form_compose vpush vsplit);
66 sub custom_field_spec {
70 my $CF_char = '[\sa-z0-9_ :()/-]';
71 my $CF_name = $CF_char . '+';
72 $CF_name = '(' . $CF_name . ')' if $capture;
74 my $new_style = 'CF\.\{'.$CF_name.'\}';
75 my $old_style = 'C(?:ustom)?F(?:ield)?-'.$CF_name;
77 return '(?i:' . join('|', $new_style, $old_style) . ')';
84 my $field = '[a-z][a-z0-9_-]*';
85 $field = '(' . $field . ')' if $capture;
87 my $custom_field = __PACKAGE__->custom_field_spec($capture);
89 return '(?i:' . join('|', $field, $custom_field) . ')';
92 # WARN: this code is duplicated in bin/rt.in,
93 # change both functions at once
98 foreach (split /\s*,\s*/, $list) {
99 push @elts, /^(\d+)-(\d+)$/? ($1..$2): $_;
102 return map $_->[0], # schwartzian transform
104 defined $a->[1] && defined $b->[1]?
107 :!defined $a->[1] && !defined $b->[1]?
110 # mix, number must be first
111 :defined $a->[1]? -1: 1
113 map [ $_, (defined( /^(\d+)$/ )? $1: undef), lc($_) ],
117 # Returns a reference to an array of parsed forms.
121 my @lines = split /\n/, $_[0];
122 my ($c, $o, $k, $e) = ("", [], {}, "");
123 my $field = __PACKAGE__->field_spec;
127 my $line = shift @lines;
129 next LINE if $line eq '';
132 # We reached the end of one form. We'll ignore it if it was
133 # empty, and store it otherwise, errors and all.
134 if ($e || $c || @$o) {
135 push @forms, [ $c, $o, $k, $e ];
136 $c = ""; $o = []; $k = {}; $e = "";
140 elsif ($state != -1) {
141 if ($state == 0 && $line =~ /^#/) {
142 # Read an optional block of comments (only) at the start
146 while (@lines && $lines[0] =~ /^#/) {
147 $c .= "\n".shift @lines;
151 elsif ($state <= 1 && $line =~ /^($field):(?:\s+(.*))?$/i) {
152 # Read a field: value specification.
155 $v[0] = '' unless defined $v[0];
157 # Read continuation lines, if any.
158 while (@lines && ($lines[0] eq '' || $lines[0] =~ /^\s+/)) {
159 push @v, shift @lines;
161 pop @v while (@v && $v[-1] eq '');
163 # Strip longest common leading indent from text.
165 foreach my $ls (map {/^(\s+)/} @v[1..$#v]) {
166 $ws = $ls if (!$ws || length($ls) < length($ws));
170 shift @v while (@v && $v[0] eq '');
172 push(@$o, $f) unless exists $k->{$f};
173 vpush($k, $f, join("\n", @v));
177 elsif ($line =~ /^#/) {
178 # We've found a syntax error, so we'll reconstruct the
179 # form parsed thus far, and add an error marker. (>>)
181 $e = form_compose([[ "", $o, $k, "" ]]);
182 $e.= $line =~ /^>>/ ? "$line\n" : ">> $line\n";
186 # We saw a syntax error earlier, so we'll accumulate the
187 # contents of this form until the end.
191 push(@forms, [ $c, $o, $k, $e ]) if ($e || $c || @$o);
193 foreach my $l (keys %$k) {
194 $k->{$l} = vsplit($k->{$l}) if (ref $k->{$l} eq 'ARRAY');
200 # Returns text representing a set of forms.
205 foreach my $form (@$forms) {
206 my ($c, $o, $k, $e) = @$form;
219 foreach my $key (@$o) {
221 my @values = (ref $k->{$key} eq 'ARRAY') ?
225 $sp = " "x(length("$key: "));
226 $sp = " "x4 if length($sp) > 16;
228 foreach my $v (@values) {
229 $v = '' unless defined $v;
235 push @lines, "$line\n\n";
238 elsif (@lines && $lines[-1] !~ /\n\n$/) {
241 push @lines, "$key: $v\n\n";
244 length($line)+length($v)-rindex($line, "\n") >= 70)
249 $line = $line ? "$line, $v" : "$key: $v";
253 $line = "$key:" unless @values;
256 if (@lines && $lines[-1] !~ /\n\n$/) {
261 push @lines, "$line\n";
265 $text .= join "", @lines;
273 return join "\n--\n\n", @text;
276 # Add a value to a (possibly multi-valued) hash key.
278 my ($hash, $key, $val) = @_;
279 my @val = ref $val eq 'ARRAY' ? @$val : $val;
281 if (exists $hash->{$key}) {
282 unless (ref $hash->{$key} eq 'ARRAY') {
283 my @v = $hash->{$key} ne '' ? $hash->{$key} : ();
286 push @{ $hash->{$key} }, @val;
289 $hash->{$key} = $val;
293 # "Normalise" a hash key that's known to be multi-valued.
298 foreach my $line (map {split /\n/} (ref $val eq 'ARRAY') ? @$val : ($val||''))
300 # XXX: This should become a real parser, ? la Text::ParseWords.
303 push @words, split /\s*,\s*/, $line;
309 RT::Base->_ImportOverlays();
315 RT::Interface::REST - helper functions for the REST interface.
319 Only the REST should use this module.