Add PositionInfo interface.

Fix #26

Author: Mingun

src/main/java/io/kaitai/struct/ArraySpan.java

@@ -0,0 +1,67 @@
+/**
+ * Copyright 2015-2020 Kaitai Project: MIT license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package io.kaitai.struct;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Span that represents positional information of array field and each of it
+ * elements. Spans of items is available in the {@link #items} field.
+ *
+ * @since 0.10
+ */
+public class ArraySpan extends Span {
+    /** Individual span of the each item in the array. */
+    public final List<Span> items;
+
+    /**
+     * Creates a span of array that starts at the current stream offset and
+     * ends at the unknown position.
+     *
+     * @param io the stream to get positional information
+     */
+    public ArraySpan(KaitaiStream io) {
+        super(io);
+        items = new ArrayList<Span>();
+    }
+
+    public ArraySpan(KaitaiStream io, int size) {
+        super(io);
+        items = new ArrayList<Span>(size);
+    }
+
+    /**
+     * Appends a new span of array item from current stream position to the end-of-stream
+     * to this span
+     *
+     * @param io Stream used to inquire current position
+     * @return A new span, added to the internal list of item spans
+     */
+    public Span addItem(KaitaiStream io) {
+        final Span span = new Span(io);
+        items.add(span);
+        return span;
+    }
+}

src/main/java/io/kaitai/struct/PositionInfo.java

@@ -0,0 +1,55 @@
+/**
+ * Copyright 2015-2020 Kaitai Project: MIT license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package io.kaitai.struct;
+
+import java.util.Map;
+
+/**
+ * This interface is implemented by each {@link KaitaiStruct} successor, if
+ * class was generated with positional information.
+ * <p>
+ * If you want to work with generated structures in the generic way, you can use
+ * following code snipped to deal with positions information:
+ * <code>
+ * final KaitaiStruct struct = ...;
+ * // Generator generates classes, that implements this interface,
+ * // if debug mode/positions-info is enabled
+ * if (struct instanceof PositionInfo) {
+ *     final PositionInfo info = (PositionInfo)struct;
+ *     //...
+ * }
+ * </code>
+ *
+ * @since 0.10
+ */
+public interface PositionInfo {
+    /**
+     * Information about each struct field. If field is an array, then corresponding
+     * {@code Span} will be of {@link ArraySpan} instance. Map keys is equals to the
+     * names of the java methods/fields in the generated class.
+     *
+     * @return the map from field name to field span information.
+     */
+    Map<String, Span> _spans();
+}

src/main/java/io/kaitai/struct/Span.java

@@ -0,0 +1,88 @@
+/**
+ * Copyright 2015-2020 Kaitai Project: MIT license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package io.kaitai.struct;
+
+/**
+ * Information about positions of parsed value in the streams.
+ *
+ * @since 0.10
+ */
+public class Span {
+    /** Offset from begin of the root stream, for which that span was created. */
+    public final long offset;
+    /**
+     * Offset from begin of the stream, from which value was parsed. This is relative
+     * position, to get an absolute position (relative to the root stream) use
+     * {@link #absoluteStart()}. That offset is always non-negative.
+     */
+    public final long start;
+    /**
+     * Offset from begin of the stream, from which value was parsed. This is relative
+     * position, to get an absolute position (relative to the root stream) use
+     * {@link #absoluteEnd()}.
+     * <p>
+     * If that offset is negative, then value wasn't parsed yet or exception was
+     * thrown while parsing value.
+     */
+    public long end = -1;
+
+    /**
+     * Creates a span that starts at the current stream offset and ends at
+     * the unknown position.
+     *
+     * @param io the stream to get the positional information
+     */
+    public Span(KaitaiStream io) {
+        this(io.offset(), io.pos());
+    }
+    private Span(long offset, long start) {
+        this.offset = offset;
+        this.start = start;
+    }
+
+    /**
+     * Offset to the start of this span relative to the root stream.
+     *
+     * @return start offset from the root stream
+     */
+    public long absoluteStart() { return offset + start; }
+    /**
+     * Offset to the end of this span relative to the root stream.
+     * <p>
+     * If that offset is negative, then value wasn't parsed yet or exception was
+     * thrown while parsing value.
+     *
+     * @return start offset from the root stream or negative value if value not yet parsed
+     */
+    public long absoluteEnd() { return end < 0 ? -1 : offset + end; }
+    /**
+     * Size of this span in bytes.
+     * <p>
+     * If size is negative, then value wasn't parsed yet or exception was
+     * thrown while parsing value.
+     *
+     * @return size of the span in bytes
+     */
+    public long size() { return end < 0 ? -1 : end - start; }
+}