org.eclipse.jface.text.source.ICharacterPairMatcher Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jface.text Show documentation
This is org.eclipse.jface.text jar used by Scout SDK
The newest version!
/*******************************************************************************
 * 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.
 * 
 * 
 * In order to provide backward compatibility for clients of ICharacterPairMatcher,
 * extension interfaces are used to provide a means of evolution. The following extension interface
 * exists:
 * 

 * {@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.
 * 
 * 
 * 
 * Clients may implement this interface and its extension interface or use the default
 * implementation provided by DefaultCharacterPairMatcher.
 * 
 * 
 * @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 match
	 * 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.
	 * 
	 * 
	 * 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)}
	 * .
	 * 
	 * 
	 * @param document the document to work on
	 * @param offset the start offset
	 * @return the minimal region containing the peer characters or null 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 RIGHT or LEFT
	 */
	int getAnchor();
}