1 package org.apache.maven.doxia.module.apt;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import org.apache.maven.doxia.util.DoxiaUtils;
23
24 /**
25 * A collection of utility methods for dealing with APT documents.
26 *
27 * @author ltheussl
28 * @since 1.1
29 * @version $Id: AptUtils.java 747735 2009-02-25 10:43:09Z ltheussl $
30 */
31 public class AptUtils
32 {
33
34 /**
35 * Replace all characters in a text.
36 *
37 * <pre>
38 * AptTools.encodeFragment( null ) = null
39 * AptTools.encodeFragment( "" ) = ""
40 * AptTools.encodeFragment( "http://www.google.com" ) = "httpwwwgooglecom"
41 * </pre>
42 *
43 * @param text the String to check, may be null.
44 * @return the text with only letter and digit, null if null String input.
45 * @deprecated This method was used for the original apt format, which
46 * removed all non alphanumeric characters from anchors.
47 * Use {@link #encodeAnchor(String)} instead.
48 */
49 public static String encodeFragment( String text )
50 {
51 if ( text == null )
52 {
53 return null;
54 }
55
56 return linkToKey( text );
57 }
58
59 /**
60 * Checks if the given string corresponds to an external URI,
61 * ie is not a link within the same document nor a link to another
62 * document within the same site. This forwards to
63 * {@link org.apache.maven.doxia.util.DoxiaUtils#isExternalLink(String)}.
64 *
65 * @param link The link to check.
66 * @return True if DoxiaUtils.isExternalLink(link) returns true.
67 *
68 * @see org.apache.maven.doxia.util.DoxiaUtils#isExternalLink(String)
69 * @see #isInternalLink(String)
70 * @see #isLocalLink(String)
71 */
72 public static boolean isExternalLink( String link )
73 {
74 return DoxiaUtils.isExternalLink( link );
75 }
76
77 /**
78 * Checks if the given string corresponds to an internal link,
79 * ie it is a link to an anchor within the same document.
80 *
81 * @param link The link to check.
82 * @return True if link is neither an {@link #isExternalLink(String) external}
83 * nor a {@link #isLocalLink(String) local} link.
84 *
85 * @see org.apache.maven.doxia.util.DoxiaUtils#isInternalLink(String)
86 * @see #isExternalLink(String)
87 * @see #isLocalLink(String)
88 */
89 public static boolean isInternalLink( String link )
90 {
91 return ( !isExternalLink( link ) && !isLocalLink( link ) );
92 }
93
94 /**
95 * Checks if the given string corresponds to a relative link to another document
96 * within the same site.
97 *
98 * @param link The link to check.
99 * @return True if the link starts with either "/", "./" or "../".
100 *
101 * @see org.apache.maven.doxia.util.DoxiaUtils#isLocalLink(String)
102 * @see #isExternalLink(String)
103 * @see #isInternalLink(String)
104 */
105 public static boolean isLocalLink( String link )
106 {
107 return ( link.startsWith( "/" ) || link.startsWith( "./" ) || link.startsWith( "../" ) );
108 }
109
110 /**
111 * Transforms the given text such that it can be used as a link.
112 * All non-LetterOrDigit characters are removed and the remaining
113 * characters are transformed to lower-case.
114 *
115 * @param text The text to transform.
116 * @return The text with all non-LetterOrDigit characters removed.
117 * @deprecated This method was used for the original apt format, which
118 * removed all non alphanumeric characters from anchors.
119 * Use {@link #encodeAnchor(String)} instead.
120 */
121 public static String linkToKey( String text )
122 {
123 int length = text.length();
124 StringBuffer buffer = new StringBuffer( length );
125
126 for ( int i = 0; i < length; ++i )
127 {
128 char c = text.charAt( i );
129 if ( Character.isLetterOrDigit( c ) )
130 {
131 buffer.append( Character.toLowerCase( c ) );
132 }
133 }
134
135 return buffer.toString();
136 }
137
138 /**
139 * Construct a valid anchor. This is a simplified version of
140 * {@link org.apache.maven.doxia.util.DoxiaUtils#encodeId(String)}
141 * to ensure the anchor is a valid Doxia id.
142 * The procedure is identical to the one in
143 * {@link org.apache.maven.doxia.util.HtmlTools#encodeId(String)}:
144 *
145 * <ol>
146 * <li> Trim the id</li>
147 * <li> If the first character is not a letter, prepend the letter 'a'</li>
148 * <li> Any space is replaced with an underscore '_'</li>
149 * <li> Remove any non alphanumeric characters except ':', '_', '.', '-'.</li>
150 * </ol>
151 *
152 * @param id The id to be encoded.
153 * @return The trimmed and encoded id, or null if id is null.
154 */
155 public static String encodeAnchor( String id )
156 {
157 if ( id == null )
158 {
159 return null;
160 }
161
162 id = id.trim();
163
164 int length = id.length();
165 StringBuffer buffer = new StringBuffer( length );
166
167 for ( int i = 0; i < length; ++i )
168 {
169 char c = id.charAt( i );
170
171 if ( ( i == 0 ) && ( !Character.isLetter( c ) ) )
172 {
173 buffer.append( 'a' );
174 }
175
176 if ( c == ' ' )
177 {
178 buffer.append( '_' );
179 }
180 else if ( ( Character.isLetterOrDigit( c ) ) || ( c == '-' ) || ( c == '_' ) || ( c == ':' )
181 || ( c == '.' ) )
182 {
183 buffer.append( c );
184 }
185 }
186
187 return buffer.toString();
188 }
189
190 private AptUtils()
191 {
192 // utility class
193 }
194 }