Mercurial > hg > truffle

comparison graal/com.oracle.truffle.api/src/com/oracle/truffle/api/SourceSection.java @ 9989:b9b8af46c2b7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Upgrade the documentation for SourceSection, especially with respect to the specification of text locations.
author Michael Van De Vanter <michael.van.de.vanter@oracle.com>
date Mon, 10 Jun 2013 16:46:26 -0700
parents e210293dca77
children 494b818b527c
comparison
equal deleted inserted replaced
9969:b8b4d7f3e4aa 9989:b9b8af46c2b7
21 * questions. 21 * questions.
22 */ 22 */
23 package com.oracle.truffle.api; 23 package com.oracle.truffle.api;
24 24
25 /** 25 /**
26 * Represents a section in the source code of a guest language program. 26 * Represents a contiguous text section within the source code of a guest language program.
27 */ 27 */
28 public class SourceSection { 28 public class SourceSection {
29 29
30 private final Source source; 30 private final Source source;
31 private final String identifier; 31 private final String identifier;
33 private final int startColumn; 33 private final int startColumn;
34 private final int charIndex; 34 private final int charIndex;
35 private final int charLength; 35 private final int charLength;
36 36
37 /** 37 /**
38 * Creates a new object representing a section in the source code of a guest language program. 38 * Creates a new object representing a contiguous text section within the source code of a guest
39 * language program.
40 * <p>
41 * The starting location of the section is specified using two different coordinate:
42 * <ul>
43 * <li><b>(row, column)</b>: rows and columns are 1-based, so the first character in a source
44 * file is at position {@code (1,1)}.</li>
45 * <li><b>character index</b>: 0-based offset of the character from the beginning of the source,
46 * so the first character in a file is at index {@code 0}.</li>
47 * </ul>
48 * The <b>newline</b> that terminates each line counts as a single character for the purpose of
49 * a character index. The (row,column) coordinates of a newline character should never appear in
50 * a text section.
51 * <p>
39 * 52 *
40 * @param source object representing the source program this is should be a section of 53 * @param source object representing the complete source program that contains this section
41 * @param identifier an identifier used when printing the section 54 * @param identifier an identifier used when printing the section
42 * @param startLine the index of the start line of the section 55 * @param startLine the 1-based number of the start line of the section
43 * @param startColumn the index of the start column of the section 56 * @param startColumn the 1-based number of the start column of the section
44 * @param charIndex the index of the first character of the section 57 * @param charIndex the 0-based index of the first character of the section
45 * @param charLength the length of the section in number of characters 58 * @param charLength the length of the section in number of characters
46 */ 59 */
47 public SourceSection(Source source, String identifier, int startLine, int startColumn, int charIndex, int charLength) { 60 public SourceSection(Source source, String identifier, int startLine, int startColumn, int charIndex, int charLength) {
48 this.source = source; 61 this.source = source;
49 this.identifier = identifier; 62 this.identifier = identifier;
52 this.charIndex = charIndex; 65 this.charIndex = charIndex;
53 this.charLength = charLength; 66 this.charLength = charLength;
54 } 67 }
55 68
56 /** 69 /**
57 * Returns the source object representing the source program this is a section of. 70 * Returns the object representing the source program that contains this section.
58 * 71 *
59 * @return the source object 72 * @return the source object
60 */ 73 */
61 public final Source getSource() { 74 public final Source getSource() {
62 return source; 75 return source;
63 } 76 }
64 77
65 /** 78 /**
66 * Returns the index of the start line of this source section (inclusive). 79 * Returns 1-based line number of the first character in this source section (inclusive).
67 * 80 *
68 * @return the start line 81 * @return the starting line number
69 */ 82 */
70 public final int getStartLine() { 83 public final int getStartLine() {
71 return startLine; 84 return startLine;
72 } 85 }
73 86
74 /** 87 /**
75 * Returns the index of the start column of this source section (inclusive). 88 * Returns the 1-based column number of the first character in this source section (inclusive).
76 * 89 *
77 * @return the start column 90 * @return the starting column number
78 */ 91 */
79 public final int getStartColumn() { 92 public final int getStartColumn() {
80 return startColumn; 93 return startColumn;
81 } 94 }
82 95
83 /** 96 /**
84 * Returns the index of the first character of this section. All characters of the source can be 97 * Returns the 0-based index of the first character in this source section.
85 * retrieved via the {@link Source#getCode()} method. 98 * <p>
99 * The complete text of the source that contains this section can be retrieved via
100 * {@link Source#getCode()}.
86 * 101 *
87 * @return the character index 102 * @return the starting character index
88 */ 103 */
89 public final int getCharIndex() { 104 public final int getCharIndex() {
90 return charIndex; 105 return charIndex;
91 } 106 }
92 107
93 /** 108 /**
94 * Returns the length of this section in characters. All characters of the source can be 109 * Returns the length of this source section in characters.
95 * retrieved via the {@link Source#getCode()} method. 110 * <p>
111 * The complete text of the source that contains this section can be retrieved via
112 * {@link Source#getCode()}.
96 * 113 *
97 * @return the character length 114 * @return the number of characters in the section
98 */ 115 */
99 public final int getCharLength() { 116 public final int getCharLength() {
100 return charLength; 117 return charLength;
101 } 118 }
102 119
108 public final String getIdentifier() { 125 public final String getIdentifier() {
109 return identifier; 126 return identifier;
110 } 127 }
111 128
112 /** 129 /**
113 * Returns the code represented by this code section. 130 * Returns text of the code represented by this source section.
114 * 131 *
115 * @return the code as a String object 132 * @return the code as a String object
116 */ 133 */
117 public final String getCode() { 134 public final String getCode() {
118 return getSource().getCode().substring(charIndex, charIndex + charLength); 135 return getSource().getCode().substring(charIndex, charIndex + charLength);