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 */ 30 public class AptUtils 31 { 32 33 /** 34 * Replace all characters in a text. 35 * 36 * <pre> 37 * AptTools.encodeFragment( null ) = null 38 * AptTools.encodeFragment( "" ) = "" 39 * AptTools.encodeFragment( "http://www.google.com" ) = "httpwwwgooglecom" 40 * </pre> 41 * 42 * @param text the String to check, may be null. 43 * @return the text with only letter and digit, null if null String input. 44 * @deprecated This method was used for the original apt format, which 45 * removed all non alphanumeric characters from anchors. 46 * Use {@link #encodeAnchor(String)} instead. 47 */ 48 public static String encodeFragment( String text ) 49 { 50 if ( text == null ) 51 { 52 return null; 53 } 54 55 return linkToKey( text ); 56 } 57 58 /** 59 * Checks if the given string corresponds to an external URI, 60 * ie is not a link within the same document nor a link to another 61 * document within the same site. This forwards to 62 * {@link org.apache.maven.doxia.util.DoxiaUtils#isExternalLink(String)}. 63 * 64 * @param link The link to check. 65 * @return True if DoxiaUtils.isExternalLink(link) returns true. 66 * @see org.apache.maven.doxia.util.DoxiaUtils#isExternalLink(String) 67 * @see #isInternalLink(String) 68 * @see #isLocalLink(String) 69 */ 70 public static boolean isExternalLink( String link ) 71 { 72 return DoxiaUtils.isExternalLink( link ); 73 } 74 75 /** 76 * Checks if the given string corresponds to an internal link, 77 * ie it is a link to an anchor within the same document. 78 * 79 * @param link The link to check. 80 * @return True if link is neither an {@link #isExternalLink(String) external} 81 * nor a {@link #isLocalLink(String) local} link. 82 * @see org.apache.maven.doxia.util.DoxiaUtils#isInternalLink(String) 83 * @see #isExternalLink(String) 84 * @see #isLocalLink(String) 85 */ 86 public static boolean isInternalLink( String link ) 87 { 88 return ( !isExternalLink( link ) && !isLocalLink( link ) ); 89 } 90 91 /** 92 * Checks if the given string corresponds to a relative link to another document 93 * within the same site. 94 * 95 * @param link The link to check. 96 * @return True if the link starts with either "/", "./" or "../". 97 * @see org.apache.maven.doxia.util.DoxiaUtils#isLocalLink(String) 98 * @see #isExternalLink(String) 99 * @see #isInternalLink(String) 100 */ 101 public static boolean isLocalLink( String link ) 102 { 103 return ( link.startsWith( "/" ) || link.startsWith( "./" ) || link.startsWith( "../" ) ); 104 } 105 106 /** 107 * Transforms the given text such that it can be used as a link. 108 * All non-LetterOrDigit characters are removed and the remaining 109 * characters are transformed to lower-case. 110 * 111 * @param text The text to transform. 112 * @return The text with all non-LetterOrDigit characters removed. 113 * @deprecated This method was used for the original apt format, which 114 * removed all non alphanumeric characters from anchors. 115 * Use {@link #encodeAnchor(String)} instead. 116 */ 117 public static String linkToKey( String text ) 118 { 119 int length = text.length(); 120 StringBuilder buffer = new StringBuilder( length ); 121 122 for ( int i = 0; i < length; ++i ) 123 { 124 char c = text.charAt( i ); 125 if ( Character.isLetterOrDigit( c ) ) 126 { 127 buffer.append( Character.toLowerCase( c ) ); 128 } 129 } 130 131 return buffer.toString(); 132 } 133 134 /** 135 * Construct a valid anchor. This is a simplified version of 136 * {@link org.apache.maven.doxia.util.DoxiaUtils#encodeId(String)} 137 * to ensure the anchor is a valid Doxia id. 138 * The procedure is identical to the one in 139 * {@link org.apache.maven.doxia.util.HtmlTools#encodeId(String)}: 140 * 141 * <ol> 142 * <li> Trim the id</li> 143 * <li> If the first character is not a letter, prepend the letter 'a'</li> 144 * <li> Any space is replaced with an underscore '_'</li> 145 * <li> Remove any non alphanumeric characters except ':', '_', '.', '-'.</li> 146 * </ol> 147 * 148 * @param id The id to be encoded. 149 * @return The trimmed and encoded id, or null if id is null. 150 */ 151 public static String encodeAnchor( String id ) 152 { 153 if ( id == null ) 154 { 155 return null; 156 } 157 158 id = id.trim(); 159 160 int length = id.length(); 161 StringBuilder buffer = new StringBuilder( length ); 162 163 for ( int i = 0; i < length; ++i ) 164 { 165 char c = id.charAt( i ); 166 167 if ( ( i == 0 ) && ( !Character.isLetter( c ) ) ) 168 { 169 buffer.append( 'a' ); 170 } 171 172 if ( c == ' ' ) 173 { 174 buffer.append( '_' ); 175 } 176 else if ( ( Character.isLetterOrDigit( c ) ) || ( c == '-' ) || ( c == '_' ) || ( c == ':' ) 177 || ( c == '.' ) ) 178 { 179 buffer.append( c ); 180 } 181 } 182 183 return buffer.toString(); 184 } 185 186 private AptUtils() 187 { 188 // utility class 189 } 190 }