| /******************************************************************************* |
| * Copyright (c) 2000, 2012 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.jface.text.source; |
| |
| import org.eclipse.jface.text.IDocument; |
| import org.eclipse.jface.text.IRegion; |
| |
| /** |
| * A character pair matcher finds to a character at a certain document offset the matching peer |
| * character. It is the matchers responsibility to define the concepts of "matching" and "peer". The |
| * matching process starts at a given offset. Starting of this offset, the matcher chooses a |
| * character close to this offset. The anchor defines whether the chosen character is left or right |
| * of the initial offset. The matcher then searches for the matching peer character of the chosen |
| * character and if it finds one, delivers the minimal region of the document that contains both |
| * characters. |
| * |
| * <p> |
| * In order to provide backward compatibility for clients of <code>ICharacterPairMatcher</code>, |
| * extension interfaces are used to provide a means of evolution. The following extension interface |
| * exists: |
| * <ul> |
| * <li>{@link org.eclipse.jface.text.source.ICharacterPairMatcherExtension} since version 3.8 |
| * introducing the concept of matching peer character and enclosing peer characters for a given |
| * selection.</li> |
| * </ul> |
| * </p> |
| * <p> |
| * Clients may implement this interface and its extension interface or use the default |
| * implementation provided by <code>DefaultCharacterPairMatcher</code>. |
| * </p> |
| * |
| * @see org.eclipse.jface.text.source.ICharacterPairMatcherExtension |
| * @since 2.1 |
| */ |
| public interface ICharacterPairMatcher { |
| |
| /** |
| * Indicates the anchor value "right". |
| */ |
| int RIGHT= 0; |
| /** |
| * Indicates the anchor value "left". |
| */ |
| int LEFT= 1; |
| |
| |
| /** |
| * Disposes this pair matcher. |
| */ |
| void dispose(); |
| |
| /** |
| * Clears this pair matcher. I.e. the matcher throws away all state it might |
| * remember and prepares itself for a new call of the <code>match</code> |
| * method. |
| */ |
| void clear(); |
| |
| /** |
| * Starting at the given offset, the matcher chooses a character close to this offset. The |
| * matcher then searches for the matching peer character of the chosen character and if it finds |
| * one, returns the minimal region of the document that contains both characters. |
| * |
| * <p> |
| * Since version 3.8 the recommended way for finding matching peers is to use |
| * {@link org.eclipse.jface.text.source.ICharacterPairMatcherExtension#match(IDocument, int, int)} |
| * . |
| * </p> |
| * |
| * @param document the document to work on |
| * @param offset the start offset |
| * @return the minimal region containing the peer characters or <code>null</code> if there is no |
| * peer character. |
| */ |
| IRegion match(IDocument document, int offset); |
| |
| /** |
| * Returns the anchor for the region of the matching peer characters. The anchor says whether |
| * the character that has been chosen to search for its peer character has been the left or the |
| * right character of the pair. |
| * |
| * @return <code>RIGHT</code> or <code>LEFT</code> |
| */ |
| int getAnchor(); |
| } |