01: /*******************************************************************************
02: * Copyright (c) 2000, 2004 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.jface.text.source.translation;
11:
12: import java.io.IOException;
13:
14: /**
15: * A tag handler is responsible to
16: * - handle the attributes for the tags it supports
17: * - translate the tag sequence including attributes to another language
18: * - back-translate relative line offsets.
19: * <p>
20: * Tag handlers are used by translators via tag handler factories. The factory
21: * can either return a new tag or one that already has some attributes. </p>
22: *
23: * @see org.eclipse.jface.text.source.translation.ITranslator
24: * @see org.eclipse.jface.text.source.translation.ITagHandlerFactory
25: * @since 3.0
26: */
27: public interface ITagHandler {
28:
29: /**
30: * Tells whether this handler can handle the given tag.
31: *
32: * @param tag the tag to check
33: * @return <code>true</code> if this handler handles the given tag
34: */
35: boolean canHandleTag(String tag);
36:
37: /**
38: * Tells whether this handler can handle the given text. Most
39: * likely the handler will check if the text contains a tag
40: * that he can handle.
41: *
42: * @param text the text to check
43: * @return <code>true</code> if this handler handles the given text
44: */
45: boolean canHandleText(String text);
46:
47: /**
48: * Adds an attribute to this tag handler.
49: *
50: * @param name the name of the attribute
51: * @param value the attribute value
52: * @param sourceLineNumber the line number of the attribute in the source or <code>-1</code> if unknown
53: */
54: void addAttribute(String name, String value, int sourceLineNumber);
55:
56: /**
57: * Resets this handler and sets the current tag to the given tag.
58: * A handler can handle more than one tag but only one tag at a time.
59: * <p>
60: * Resetting the handler clears the attributes.</p>
61: *
62: * @param tag the tag to check
63: */
64: void reset(String tag);
65:
66: /**
67: * Writes the tag and line mapping information to the
68: * given translator result collector.
69: *
70: * @param resultCollector the translator's result collector
71: * @param sourceLineNumber the line number of the attribute in the source or <code>-1</code> if unknown
72: * @throws IOException
73: */
74: void processEndTag(ITranslatorResultCollector resultCollector,
75: int sourceLineNumber) throws IOException;
76:
77: /**
78: * Computes the offset in the source line that corresponds
79: * to the given offset in the translated line.
80: *
81: * @param sourceLine the source line
82: * @param translatedLine the translated line
83: * @param offsetInTranslatedLine the offset in the translated line
84: * @return the offset in the source line or <code>-1</code> if
85: * it was not possible to compute the offset
86: */
87: int backTranslateOffsetInLine(String sourceLine,
88: String translatedLine, int offsetInTranslatedLine);
89: }
|