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$ 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 StringBuilder buffer = new StringBuilder( 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 StringBuilder buffer = new StringBuilder( 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 }