1 /******************************************************************************* 2 * Copyright (c) 2000, 2012 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.jface.text.source; 15 16 import org.eclipse.jface.text.IDocument; 17 import org.eclipse.jface.text.IRegion; 18 19 /** 20 * A character pair matcher finds to a character at a certain document offset the matching peer 21 * character. It is the matchers responsibility to define the concepts of "matching" and "peer". The 22 * matching process starts at a given offset. Starting of this offset, the matcher chooses a 23 * character close to this offset. The anchor defines whether the chosen character is left or right 24 * of the initial offset. The matcher then searches for the matching peer character of the chosen 25 * character and if it finds one, delivers the minimal region of the document that contains both 26 * characters. 27 * 28 * <p> 29 * In order to provide backward compatibility for clients of <code>ICharacterPairMatcher</code>, 30 * extension interfaces are used to provide a means of evolution. The following extension interface 31 * exists: 32 * </p> 33 * <ul> 34 * <li>{@link org.eclipse.jface.text.source.ICharacterPairMatcherExtension} since version 3.8 35 * introducing the concept of matching peer character and enclosing peer characters for a given 36 * selection.</li> 37 * </ul> 38 * <p> 39 * Clients may implement this interface and its extension interface or use the default 40 * implementation provided by <code>DefaultCharacterPairMatcher</code>. 41 * </p> 42 * 43 * @see org.eclipse.jface.text.source.ICharacterPairMatcherExtension 44 * @since 2.1 45 */ 46 public interface ICharacterPairMatcher { 47 48 /** 49 * Indicates the anchor value "right". 50 */ 51 int RIGHT= 0; 52 /** 53 * Indicates the anchor value "left". 54 */ 55 int LEFT= 1; 56 57 58 /** 59 * Disposes this pair matcher. 60 */ dispose()61 void dispose(); 62 63 /** 64 * Clears this pair matcher. I.e. the matcher throws away all state it might 65 * remember and prepares itself for a new call of the <code>match</code> 66 * method. 67 */ clear()68 void clear(); 69 70 /** 71 * Starting at the given offset, the matcher chooses a character close to this offset. The 72 * matcher then searches for the matching peer character of the chosen character and if it finds 73 * one, returns the minimal region of the document that contains both characters. 74 * 75 * <p> 76 * Since version 3.8 the recommended way for finding matching peers is to use 77 * {@link org.eclipse.jface.text.source.ICharacterPairMatcherExtension#match(IDocument, int, int)} 78 * . 79 * </p> 80 * 81 * @param document the document to work on 82 * @param offset the start offset 83 * @return the minimal region containing the peer characters or <code>null</code> if there is no 84 * peer character. 85 */ match(IDocument document, int offset)86 IRegion match(IDocument document, int offset); 87 88 /** 89 * Returns the anchor for the region of the matching peer characters. The anchor says whether 90 * the character that has been chosen to search for its peer character has been the left or the 91 * right character of the pair. 92 * 93 * @return <code>RIGHT</code> or <code>LEFT</code> 94 */ getAnchor()95 int getAnchor(); 96 } 97