001    // Copyright 2008 Waterken Inc. under the terms of the MIT X license
002    // found at http://www.opensource.org/licenses/mit-license.html
003    package org.ref_send.log;
004    
005    import java.io.Serializable;
006    
007    import org.joe_e.Powerless;
008    import org.joe_e.Struct;
009    import org.joe_e.array.IntArray;
010    import org.joe_e.array.PowerlessArray;
011    import org.ref_send.Record;
012    import org.ref_send.deserializer;
013    import org.ref_send.name;
014    
015    /**
016     * A source code location.
017     */
018    public class
019    CallSite extends Struct implements Powerless, Record, Serializable {
020        static private final long serialVersionUID = 1L;
021        
022        /**
023         * call site's human meaningful name within the {@linkplain #source}
024         */
025        public final String name;
026    
027        /**
028         * path to the source code containing the call site
029         */
030        public final String source;
031        
032        /**
033         * call site's position within the {@linkplain #source} (optional)
034         * <p>
035         * The expected structure of this table defines a span from the start of the
036         * relevant source code to the end. The first row in the table is the start
037         * of the span and the second row is the end of the span. Each row lists the
038         * line number followed by the column number. For example, a span of code
039         * starting on line 5, column 8 and ending on line 6, column 12 is encoded
040         * as:
041         * </p>
042         * <p>
043         * <code>[ [ 5, 8 ], [ 6, 12 ] ]</code>
044         * </p>
045         * <p>
046         * The delimited span is inclusive, meaning the character at line 6, column
047         * 12 is included in the span defined above.
048         * </p>
049         * <p>
050         * If the end of the span is unknown, it may be omitted. If the column
051         * number is unknown, it may also be omitted. For example, in the case where
052         * only the starting line number is known:
053         * </p>
054         * <p>
055         * <code>[ [ 5 ] ]</code>
056         * </p>
057         * <p>
058         * If source span information is unknown, this member is <code>null</code>.
059         * </p>
060         * <p>
061         * Both lines and columns are numbered starting from one, so the first
062         * character in a source file is at <code>[ 1, 1 ]</code>. A column is a
063         * UTF-16 code unit, the same unit represented by a Java <code>char</code>.
064         * Lines are separated by any character sequence considered a Unicode <a
065         * href="http://en.wikipedia.org/wiki/Newline#Unicode">line terminator</a>.
066         * </p>
067         */
068        public final PowerlessArray<IntArray> span;
069        
070        /**
071         * Constructs an instance.
072         * @param name      {@link #name}
073         * @param source    {@link #source}
074         * @param span      {@link #span}
075         */
076        public @deserializer
077        CallSite(@name("name") final String name,
078                 @name("source") final String source,
079                 @name("span") final PowerlessArray<IntArray> span) {
080            this.name = name;
081            this.source = source;
082            this.span = span;
083        }
084    }