| /* |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| */ |
| |
| package org.apache.wiki.parser; |
| |
| import java.util.ArrayList; |
| import java.util.Arrays; |
| import java.util.Iterator; |
| import java.util.List; |
| import java.util.NoSuchElementException; |
| import java.util.StringTokenizer; |
| |
| import org.apache.log4j.Logger; |
| import org.jdom2.Attribute; |
| |
| /** |
| * Parses JSPWiki-style "augmented" link markup into a Link object |
| * containing the link text, link reference, and any optional link |
| * attributes (as JDOM Attributes). |
| * <p> |
| * The parser recognizes three link forms: |
| * </p> |
| * <ol> |
| * <li><tt> [Text] </tt></li> |
| * <li><tt> [Text | Link] </tt></li> |
| * <li><tt> [Text | Link | attributes] </tt></li> |
| * </ol> |
| * <p> |
| * where the attributes are space-delimited, each in the form of |
| * </p> |
| * <pre> |
| * name1='value1' name2='value2' name3='value3' (etc.) </pre> |
| * <p> |
| * If the attribute parsing fails, the parser will still return the |
| * basic link, writing a warning to the log. |
| * </p> |
| * |
| * <h3>Permitted Attributes</h3> |
| * <p> |
| * Attributes that aren't declared on <tt><a></tt> or those that |
| * permit scripting in HTML (as this is a security risk) are ignored |
| * and have no effect on parsing, nor show up in the resulting attribute |
| * list). The 'href' and 'name' attributes are also ignored as spurious. |
| * The permitted list is: 'accesskey', 'charset', 'class', 'hreflang', |
| * 'id', 'lang', 'dir', 'rel', 'rev', 'style' , 'tabindex', 'target' , |
| * 'title', and 'type'. The declared attributes that will be ignored |
| * are: 'href', 'name', 'shape', 'coords', 'onfocus', 'onblur', or any |
| * of the other 'on*' event attributes. |
| * </p> |
| * <p> |
| * The permitted attributes and target attribute values are static |
| * String arrays ({@link #PERMITTED_ATTRIBUTES} and |
| * {@link #PERMITTED_TARGET_VALUES} resp.) that could be compile-time |
| * modified (i.e., predeclared). |
| * </p> |
| * |
| * <h3>Permitted Values on Target Attribute</h3> |
| * <p> |
| * The following target names are reserved in HTML 4 and have special |
| * meanings. These are the only values permitted by the parser. |
| * <dl> |
| * <dt><b>_blank</b></dt> |
| * <dd> The user agent should load the designated document in a new, |
| * unnamed window. </dd> |
| * <dt><b>_self</b></dt> |
| * <dd> The user agent should load the document in the same frame as |
| * the element that refers to this target. </dd> |
| * <dt><b>_parent</b></dt> |
| * <dd> The user agent should load the document into the immediate |
| * FRAMESET parent of the current frame. This value is equivalent to |
| * _self if the current frame has no parent. </dd> |
| * <dt><b>_top</b></dt> |
| * <dd> The user agent should load the document into the full, |
| * original window (thus canceling all other frames). This value is |
| * equivalent to _self if the current frame has no parent. </dd> |
| * </dl> |
| * |
| * <h3>Returned Value</h3> |
| * <p> |
| * This returns a <b>Link</b> object, a public inner class with methods: |
| * <ul> |
| * <li> <tt>getText()</tt> returns the link text. </li> |
| * <li> <tt>getReference()</tt> returns the link reference value. </li> |
| * <li> <tt>attributeCount()</tt> returns the number of declared attributes. </li> |
| * <li> <tt>getAttributes()</tt> returns an iterator over any validated |
| * XHTML-compliant attributes, returned as JDOM Attributes. |
| * </li> |
| * </ul> |
| * <p> |
| * The <tt>attributeCount()</tt> method can be used to circumvent calling |
| * <tt>getAttributes()</tt>, which will create an empty Iterator rather |
| * than return a null. |
| * </p> |
| * |
| * <h3>Example: Link Form 1</h3> |
| * <p> |
| * From an incoming wikitext link of: |
| * <pre> |
| * [Acme] </pre> |
| * returns: |
| * <pre> |
| * getText(): "Acme" |
| * getReference(): "Acme" |
| * attributeCount(): 0 |
| * getAttributes(): an empty Iterator </pre> |
| * |
| * <h3>Example: Link Form 2</h3> |
| * <p> |
| * From an incoming wikitext link of: |
| * <pre> |
| * [Acme | http://www.acme.com/] </pre> |
| * returns: |
| * <pre> |
| * getText(): "Acme" |
| * getReference(): "http://www.acme.com/" |
| * attributeCount(): 0 |
| * getAttributes(): an empty Iterator </pre> |
| * |
| * <h3>Example: Link Form 3</h3> |
| * <p> |
| * From an incoming wikitext link of: |
| * </p> |
| * <pre> |
| * [Acme | http://www.acme.com/ | id='foo' rel='Next'] </pre> |
| * returns: |
| * <pre> |
| * getText(): "Acme" |
| * getReference(): "http://www.acme.com/" |
| * attributeCount(): 2 |
| * getAttributes(): an Iterator containing: |
| * JDOM Attribute: id="foo" |
| * JDOM Attribute: rel="Next" </pre> |
| * |
| * |
| * @since 2.5.10 |
| */ |
| public class LinkParser |
| { |
| private static Logger log = Logger.getLogger(LinkParser.class); |
| |
| /** Permitted attributes on links. Keep this sorted. */ |
| private static final String[] PERMITTED_ATTRIBUTES = new String[] { |
| "accesskey", "charset", "class", "dir", "hreflang", "id", "lang", |
| "rel", "rev", "style", "tabindex", "target", "title", "type" }; |
| |
| /** Permitted values on the 'target' attribute. */ |
| private static final String[] PERMITTED_TARGET_VALUES = new String[] { |
| "_blank", "_self", "_parent", "_top" }; |
| |
| private static final String EQSQUO = "='"; |
| private static final String SQUO = "'"; |
| private static final String EQ = "="; |
| private static final String TARGET = "target"; |
| private static final String DELIMS = " \t\n\r\f="; |
| |
| private static final List< Attribute > m_EMPTY = new ArrayList< >(); |
| |
| // ............ |
| |
| |
| /** |
| * Processes incoming link text, separating out the link text, the link |
| * URI, and then any specified attributes. |
| * |
| * @param linktext the wiki link text to be parsed |
| * @return a Link object containing the link text, reference, and any valid Attributes |
| * @throws ParseException if the parameter is null |
| */ |
| public Link parse( String linktext ) throws ParseException |
| { |
| if( linktext == null ) |
| { |
| throw new ParseException("null value passed to link parser"); |
| } |
| |
| Link link = null; |
| |
| try |
| { |
| // establish link text and link ref |
| int cut1 = linktext.indexOf('|'); |
| if( cut1 == -1 ) |
| { |
| // link form 1: [Acme] |
| return new Link( linktext ); |
| } |
| |
| int cut2 = cut1+1 < linktext.length() |
| ? linktext.indexOf('|', cut1+1 ) |
| : -1 ; |
| |
| if ( cut2 == -1 ) |
| { |
| // link form 2: [Acme | http://www.acme.com/] |
| // text = Acme |
| String text = linktext.substring( 0, cut1 ).trim(); |
| // ref = http://www.acme.com/ |
| String ref = linktext.substring( cut1+1 ).trim(); |
| return new Link( text, ref ); |
| } |
| |
| // link form 3: [Acme | http://www.acme.com/ | id='foo' rel='Next'] |
| String text = linktext.substring( 0, cut1 ).trim(); |
| String ref = linktext.substring( cut1+1, cut2 ).trim(); |
| // attribs = id='foo' rel='Next' |
| String attribs = linktext.substring( cut2+1 ).trim(); |
| |
| link = new Link( text, ref ); |
| |
| // parse attributes |
| // contains "='" that looks like attrib spec |
| if( attribs.indexOf(EQSQUO) != -1 ) |
| { |
| try |
| { |
| StringTokenizer tok = new StringTokenizer(attribs,DELIMS,true); |
| while ( tok.hasMoreTokens() ) |
| { |
| // get attribute name token |
| String token = tok.nextToken(DELIMS).trim(); |
| while ( isSpace(token) && tok.hasMoreTokens() ) |
| { |
| // remove all whitespace |
| token = tok.nextToken(DELIMS).trim(); |
| } |
| |
| // eat '=', break after '=' |
| require( tok, EQ ); |
| // eat opening delim |
| require( tok, SQUO ); |
| // using existing delim |
| String value = tok.nextToken(SQUO); |
| // eat closing delim |
| require( tok, SQUO ); |
| |
| if( token != null && value != null ) |
| { |
| if( Arrays.binarySearch( PERMITTED_ATTRIBUTES, token ) >= 0 ) |
| { |
| // _blank _self _parent _top |
| if( !token.equals(TARGET) |
| || Arrays.binarySearch( PERMITTED_TARGET_VALUES, value ) >= 0 ) |
| { |
| Attribute a = new Attribute(token,value); |
| link.addAttribute(a); |
| } |
| else |
| { |
| throw new ParseException("unknown target attribute value='" |
| + value + "' on link"); |
| } |
| } |
| else |
| { |
| throw new ParseException("unknown attribute name '" |
| + token + "' on link"); |
| } |
| } |
| else |
| { |
| throw new ParseException("unable to parse link attributes '" |
| + attribs + "'"); |
| |
| } |
| } |
| } |
| catch( ParseException pe ) |
| { |
| log.warn("syntax error parsing link attributes '"+attribs+"': " + pe.getMessage()); |
| } |
| catch( NoSuchElementException nse ) |
| { |
| log.warn("expected more tokens while parsing link attributes '" + attribs + "'"); |
| } |
| } |
| |
| } |
| catch( Exception e ) |
| { |
| log.warn( e.getClass().getName() + " thrown by link parser: " + e.getMessage() ); |
| } |
| |
| return link; |
| } |
| |
| |
| private String require( StringTokenizer tok, String required ) |
| throws ParseException, NoSuchElementException |
| { |
| String s = tok.nextToken(required); |
| if( !s.equals(required) ) |
| { |
| throw new ParseException("expected '"+required+"' not '"+s+"'"); |
| } |
| return s; |
| } |
| |
| |
| /** |
| * Returns true if the String <tt>s</tt> is completely |
| * composed of whitespace. |
| * |
| * @param s The string to check |
| * @return True, if "s" is all XML whitespace. |
| */ |
| public static final boolean isSpace( String s ) |
| { |
| for( int i = 0 ; i < s.length() ; i++ ) |
| { |
| if( !isSpace( s.charAt(i)) ) return false; |
| } |
| return true; |
| } |
| |
| |
| /** |
| * Returns true if char <tt>c</tt> is a member of |
| * <tt>S</tt> (space) [XML 1.1 production 3]. |
| * |
| * @param c Character to check. |
| * @return True, if the character is an XML space. |
| */ |
| public static final boolean isSpace( char c ) |
| { |
| // 0x20 = SPACE, 0x0A = LF, 0x0D = CR, 0x09 = TAB, 0x85 = NEL, 0x2028 = Line separator |
| return |
| 0x20 == c |
| || 0x0A == c |
| || 0x0D == c |
| || 0x09 == c |
| || 0x85 == c |
| || 0x2028 == c; |
| } |
| |
| |
| // ......................................................................... |
| |
| |
| /** |
| * Inner class serving as a struct containing the parsed |
| * components of a link. |
| */ |
| public static class Link |
| { |
| private String m_text; |
| private String m_ref = null; |
| private int m_interwikiPoint = -1; |
| private List<Attribute> m_attribs = null; |
| |
| /** |
| * Create a new Link with text but no reference. |
| * @param text The link text. |
| * @throws ParseException If the link text is illegal. |
| */ |
| protected Link( String text ) throws ParseException |
| { |
| setText(text); |
| } |
| |
| /** |
| * Create a new link with a given text and hyperlink (reference). |
| * |
| * @param text The link text. |
| * @param ref The hypertext reference. |
| * @throws ParseException If the link text or reference are illegal. |
| */ |
| protected Link( String text, String ref ) throws ParseException |
| { |
| setText(text); |
| setReference(ref); |
| } |
| |
| /** |
| * Sets the link text. |
| * |
| * @param text The link text. |
| * @throws ParseException If the text is illegal (e.g. null). |
| */ |
| protected void setText( String text ) throws ParseException |
| { |
| if( text == null ) |
| { |
| throw new ParseException("null link text"); |
| } |
| m_text = text; |
| } |
| |
| /** |
| * Returns the link text. |
| * |
| * @return Link text. |
| */ |
| public String getText() |
| { |
| return m_text; |
| } |
| |
| /** |
| * Sets the hypertext reference. Typically, this is an URI or an interwiki link, |
| * or a wikilink. |
| * |
| * @param ref The reference. |
| * @throws ParseException If the reference is illegal. |
| */ |
| protected void setReference( String ref ) throws ParseException |
| { |
| if( ref == null ) |
| { |
| throw new ParseException("null link reference value"); |
| } |
| m_ref = ref; |
| } |
| |
| /** |
| * Returns true, if there is a reference. |
| * |
| * @return True, if there's a reference; false otherwise. |
| */ |
| public boolean hasReference() |
| { |
| return m_ref != null; |
| } |
| |
| /** |
| * Returns the link reference, or the link text if null. |
| * |
| * @return A link reference. |
| */ |
| public String getReference() |
| { |
| return m_ref != null |
| ? m_ref |
| : m_text ; |
| } |
| |
| /** |
| * Returns true, if this Link represents an InterWiki link (of the form wiki:page). |
| * |
| * @return True, if this Link represents an InterWiki link. |
| */ |
| public boolean isInterwikiLink() |
| { |
| LinkParsingOperations lpo = new LinkParsingOperations( null ); |
| if( !hasReference() ) m_ref = m_text; |
| m_interwikiPoint = lpo.interWikiLinkAt( m_ref ); |
| return lpo.isInterWikiLink( m_ref ); |
| } |
| |
| /** |
| * Returns the name of the wiki if this is an interwiki link. |
| * <pre> |
| * Link link = new Link("Foo","Wikipedia:Foobar"); |
| * assert( link.getExternalWikiPage(), "Wikipedia" ); |
| * </pre> |
| * |
| * @return Name of the wiki, or null, if this is not an interwiki link. |
| */ |
| public String getExternalWiki() |
| { |
| if( isInterwikiLink() ) |
| { |
| return m_ref.substring( 0, m_interwikiPoint ); |
| } |
| |
| return null; |
| } |
| |
| /** |
| * Returns the wikiname part of an interwiki link. Used only with interwiki links. |
| * <pre> |
| * Link link = new Link("Foo","Wikipedia:Foobar"); |
| * assert( link.getExternalWikiPage(), "Foobar" ); |
| * </pre> |
| * |
| * @return Wikiname part, or null, if this is not an interwiki link. |
| */ |
| public String getExternalWikiPage() |
| { |
| if( isInterwikiLink() ) |
| { |
| return m_ref.substring( m_interwikiPoint+1 ); |
| } |
| |
| return null; |
| } |
| |
| /** |
| * Returns the number of attributes on this link. |
| * |
| * @return The number of attributes. |
| */ |
| public int attributeCount() |
| { |
| return m_attribs != null |
| ? m_attribs.size() |
| : 0 ; |
| } |
| |
| /** |
| * Adds another attribute to the link. |
| * |
| * @param attr A JDOM Attribute. |
| */ |
| public void addAttribute( Attribute attr ) |
| { |
| if( m_attribs == null ) |
| { |
| m_attribs = new ArrayList<>(); |
| } |
| m_attribs.add(attr); |
| } |
| |
| /** |
| * Returns an Iterator over the list of JDOM Attributes. |
| * |
| * @return Iterator over the attributes. |
| */ |
| public Iterator< Attribute > getAttributes() |
| { |
| return m_attribs != null |
| ? m_attribs.iterator() |
| : m_EMPTY.iterator() ; |
| } |
| |
| /** |
| * Returns a wikitext string representation of this Link. |
| * @return WikiText. |
| */ |
| @Override |
| public String toString() |
| { |
| StringBuilder sb = new StringBuilder(); |
| sb.append( '[' ); |
| sb.append( m_text ); |
| |
| if( m_ref != null ) |
| { |
| sb.append( ' ' ); |
| sb.append( '|' ); |
| sb.append( ' ' ); |
| sb.append( m_ref ); |
| } |
| |
| if( m_attribs != null ) |
| { |
| sb.append( ' ' ); |
| sb.append( '|' ); |
| Iterator< Attribute > it = getAttributes(); |
| while ( it.hasNext() ) |
| { |
| Attribute a = it.next(); |
| sb.append( ' ' ); |
| sb.append( a.getName() ); |
| sb.append( '=' ); |
| sb.append( '\'' ); |
| sb.append( a.getValue() ); |
| sb.append( '\'' ); |
| } |
| } |
| sb.append( ']' ); |
| return sb.toString(); |
| } |
| |
| } |
| // end inner class |
| |
| } |
