File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\MarkupText.java.html

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2004-2010, Sun Microsystems, Inc., Kohsuke Kawaguchi
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 * THE SOFTWARE.
23 */
24 package hudson;
25
26 import java.util.ArrayList;
27 import java.util.Collections;
28 import java.util.List;
29 import java.util.regex.Matcher;
30 import java.util.regex.Pattern;
31
32 /**
33 * Mutable representation of string with HTML mark up.
34 *
35 * <p>
36 * This class is used to put mark up on plain text.
37 * See {@code MarkupTextTest} for a typical usage and its result.
38 *
39 * @author Kohsuke Kawaguchi
40 * @since 1.70
41 */
42 public class MarkupText extends AbstractMarkupText {
43 private final String text;
44
45 /**
46 * Added mark up tags.
47 */
48 private final List<Tag> tags = new ArrayList<Tag>();
49
50 /**
51 * Represents one mark up inserted into text.
52 */
53 private static final class Tag implements Comparable<Tag> {
54 /**
55 * Char position of this tag in {@link MarkupText#text}.
56 * This tag is placed in front of the character of this index.
57 */
58 private final int pos;
59 private final String markup;
60
61
62 public Tag(int pos, String markup) {
63 this.pos = pos;
64 this.markup = markup;
65 }
66
67 public int compareTo(Tag that) {
68 return this.pos-that.pos;
69 }
70 }
71
72 /**
73 * Represents a substring of a {@link MarkupText}.
74 */
75 public final class SubText extends AbstractMarkupText {
76 private final int start,end;
77 private final int[] groups;
78
79 public SubText(Matcher m, int textOffset) {
80 start = m.start() + textOffset;
81 end = m.end() + textOffset;
82
83 int cnt = m.groupCount();
84 groups = new int[cnt*2];
85 for( int i=0; i<cnt; i++ ) {
86 groups[i*2 ] = m.start(i+1) + textOffset;
87 groups[i*2+1] = m.end(i+1) + textOffset;
88 }
89 }
90
91 public SubText(int start, int end) {
92 this.start = start;
93 this.end = end;
94 groups = new int[0];
95 }
96
97 @Override
98 public SubText subText(int start, int end) {
99 return MarkupText.this.subText(this.start+start,
100 end<0 ? this.end+1+end : this.start+end);
101 }
102
103 @Override
104 public String getText() {
105 return text.substring(start,end);
106 }
107
108 @Override
109 public void addMarkup(int startPos, int endPos, String startTag, String endTag) {
110 MarkupText.this.addMarkup(startPos+start, endPos+start, startTag, endTag);
111 }
112
113 /**
114 * Surrounds this subtext with the specified start tag and the end tag.
115 *
116 * <p>
117 * Start/end tag text can contain special tokens "$0", "$1", ...
118 * and they will be replaced by their {@link #group(int) group match}.
119 * "\$" can be used to escape characters.
120 */
121 public void surroundWith(String startTag, String endTag) {
122 addMarkup(0,length(),replace(startTag),replace(endTag));
123 }
124
125 /**
126 * Works like {@link #surroundWith(String, String)} except
127 * that the token replacement is not performed on parameters.
128 */
129 public void surroundWithLiteral(String startTag, String endTag) {
130 addMarkup(0,length(),startTag,endTag);
131 }
132
133 /**
134 * Surrounds this subtext with &lt;a>...&lt;/a>.
135 */
136 public void href(String url) {
137 addHyperlink(0,length(),url);
138 }
139
140 /**
141 * Gets the start index of the captured group within {@link MarkupText#getText()}.
142 *
143 * @param groupIndex
144 * 0 means the start of the whole subtext. 1, 2, ... are
145 * groups captured by '(...)' in the regexp.
146 */
147 public int start(int groupIndex) {
148 if(groupIndex==0) return start;
149 return groups[groupIndex*2-2];
150 }
151
152 /**
153 * Gets the start index of this subtext within {@link MarkupText#getText()}.
154 */
155 public int start() {
156 return start;
157 }
158
159 /**
160 * Gets the end index of the captured group within {@link MarkupText#getText()}.
161 */
162 public int end(int groupIndex) {
163 if(groupIndex==0) return end;
164 return groups[groupIndex*2-1];
165 }
166
167 /**
168 * Gets the end index of this subtext within {@link MarkupText#getText()}.
169 */
170 public int end() {
171 return end;
172 }
173
174 /**
175 * Gets the text that represents the captured group.
176 */
177 public String group(int groupIndex) {
178 if(start(groupIndex)==-1)
179 return null;
180 return text.substring(start(groupIndex),end(groupIndex));
181 }
182
183 /**
184 * How many captured groups are in this subtext.
185 * @since 1.357
186 */
187 public int groupCount() {
188 return groups.length / 2;
189 }
190
191 /**
192 * Replaces the group tokens like "$0", "$1", and etc with their actual matches.
193 */
194 public String replace(String s) {
195 StringBuilder buf = new StringBuilder(s.length() + 10);
196
197 for( int i=0; i<s.length(); i++) {
198 char ch = s.charAt(i);
199 if (ch == '\\') {// escape char
200 i++;
201 buf.append(s.charAt(i));
202 } else if (ch == '$') {// replace by group
203 i++;
204
205 ch = s.charAt(i);
206 // get the group number
207 int groupId = ch - '0';
208 if (groupId < 0 || groupId > 9) {
209 buf.append('$').append(ch);
210 } else {
211 // add the group text
212 String group = group(groupId);
213 if (group != null)
214 buf.append(group);
215 }
216
217 } else {
218 // other chars
219 buf.append(ch);
220 }
221 }
222
223 return buf.toString();
224 }
225
226 @Override
227 protected SubText createSubText(Matcher m) {
228 return new SubText(m,start);
229 }
230 }
231
232 /**
233 *
234 * @param text
235 * Plain text. This shouldn't include any markup nor escape. Those are done later in {@link #toString(boolean)}.
236 */
237 public MarkupText(String text) {
238 this.text = text;
239 }
240
241 @Override
242 public String getText() {
243 return text;
244 }
245
246 /**
247 * Returns a subtext.
248 *
249 * @param end
250 * If negative, -N means "trim the last N-1 chars". That is, (s,-1) is the same as (s,length)
251 */
252 public SubText subText(int start, int end) {
253 return new SubText(start, end<0 ? text.length()+1+end : end);
254 }
255
256 @Override
257 public void addMarkup( int startPos, int endPos, String startTag, String endTag ) {
258 rangeCheck(startPos);
259 rangeCheck(endPos);
260 if(startPos>endPos) throw new IndexOutOfBoundsException();
261
262 // when multiple tags are added to the same range, we want them to show up like
263 // <b><i>abc</i></b>, not <b><i>abc</b></i>. Also, we'd like <b>abc</b><i>def</i>,
264 // not <b>abc<i></b>def</i>. Do this by inserting them to different places.
265 tags.add(new Tag(startPos, startTag));
266 tags.add(0,new Tag(endPos,endTag));
267 }
268
269 public void addMarkup(int pos, String tag) {
270 rangeCheck(pos);
271 tags.add(new Tag(pos,tag));
272 }
273
274 private void rangeCheck(int pos) {
275 if(pos<0 || pos>text.length())
276 throw new IndexOutOfBoundsException();
277 }
278
279 /**
280 * Returns the fully marked-up text.
281 *
282 * @deprecated as of 1.350.
283 * Use {@link #toString(boolean)} to be explicit about the escape mode.
284 */
285 @Override
286 public String toString() {
287 return toString(false);
288 }
289
290 /**
291 * Returns the fully marked-up text.
292 *
293 * @param preEscape
294 * If true, the escaping is for the &lt;PRE> context. This leave SP and CR/LF intact.
295 * If false, the escape is for the normal HTML, thus SP becomes &amp;nbsp; and CR/LF becomes &lt;BR>
296 */
297 public String toString(boolean preEscape) {
298 if(tags.isEmpty())
299 return preEscape? Util.xmlEscape(text) : Util.escape(text); // the most common case
300
301 Collections.sort(tags);
302
303 StringBuilder buf = new StringBuilder();
304 int copied = 0; // # of chars already copied from text to buf
305
306 for (Tag tag : tags) {
307 if (copied<tag.pos) {
308 String portion = text.substring(copied, tag.pos);
309 buf.append(preEscape ? Util.xmlEscape(portion) : Util.escape(portion));
310 copied = tag.pos;
311 }
312 buf.append(tag.markup);
313 }
314 if (copied<text.length()) {
315 String portion = text.substring(copied, text.length());
316 buf.append(preEscape ? Util.xmlEscape(portion) : Util.escape(portion));
317 }
318
319 return buf.toString();
320 }
321
322 // perhaps this method doesn't need to be here to remain binary compatible with past versions,
323 // but having this seems to be safer.
324 @Override
325 public List<SubText> findTokens(Pattern pattern) {
326 return super.findTokens(pattern);
327 }
328
329 @Override
330 protected SubText createSubText(Matcher m) {
331 return new SubText(m,0);
332 }
333 }
334