kaitai-io#22: Implement annotations for generated stuff

src/main/java/io/kaitai/struct/annotations/Field.java

@@ -0,0 +1,60 @@
+/**
+ * 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.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation, that applied to fields, getters or setters that represents field
+ * from {@code seq} language element.
+ *
+ * @author Mingun
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD})
+public @interface Field {
+    /**
+     * Original identifier ({@code id} key) from {@code ksy} file.
+     *
+     * @return Identifier, that can differ from field name, if it clash with
+     *         Java reserved words. Empty string, if field was unnamed
+     */
+    String id();
+    /**
+     * Index of field in sequence of fields in the type
+     *
+     * @return 0-based index of field in {@code seq} language element
+     */
+    int index();
+    /**
+     * Documentation string, that attached to the field in {@code doc} language element.
+     *
+     * @return Documentation string for field. If documentation is missed, returns empty string
+     */
+    String doc();
+}

src/main/java/io/kaitai/struct/annotations/Generated.java

@@ -0,0 +1,101 @@
+/**
+ * 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.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation, that applied to Kaitai-generated classes. Visualizers can use that
+ * annotation to find classes, that contains generated stuff, that should be showed
+ * in visualization.
+ *
+ * @author Mingun
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface Generated {
+    /**
+     * Original identifier ({@code id} key) from {@code ksy} file.
+     *
+     * @return Identifier, that can differ from class name, if it clash with
+     *         Java reserved words. Can not be empty
+     */
+    String id();
+    /**
+     * Version of compiler, that generated this class.
+     *
+     * @return Version string in <a href="https://semver.org/">semver</a> format
+     */
+    String version();
+    /**
+     * Class compiled with support of position tracking. That means, that every class
+     * has following public fields (in that version of generator):
+     * <table>
+     * <tr><th>Type</th><th>Field</th><th>Description</th></tr>
+     * <tr><td>{@code Map<String, Integer>}</td><td>{@code _attrStart}</td>
+     *     <td>Start offset in root stream, where {@link Field field} or
+     *         {@link Instance instance} with specified name begins.
+     *         Used only for fields/instances, that is not repeated</td>
+     * </tr>
+     * <tr><td>{@code Map<String, Integer>}</td><td>{@code _attrEnd}</td>
+     *     <td>Start offset in root stream, where {@link Field field} or
+     *         {@link Instance instance} with specified name ends (exclusive).
+     *         Used only for fields/instances, that is not repeated</td>
+     * </tr>
+     * <tr><td>{@code Map<String, ? extends List<Integer>>}</td><td>{@code _arrStart}</td>
+     *     <td>List with start offset in root stream, where each array element of repeated
+     *         {@link Field field} or {@link Instance instance} with specified name begins.
+     *         Used only for fields/instances, that is repeated</td>
+     * </tr>
+     * <tr><td>{@code Map<String, ? extends List<Integer>>}</td><td>{@code _arrEnd}</td>
+     *     <td>List with end offset (exclusive) in root stream, where each array element of repeated
+     *         {@link Field field} or {@link Instance instance} with specified name ends.
+     *         Used only for fields/instances, that is repeated</td>
+     * </tr>
+     * </table>
+     *
+     * @return {@code true}, if position tracking is enabled and {@code false} otherwise
+     */
+    boolean posInfo();
+    /**
+     * Determines, if instantiation of user classes (related to user-types, defined
+     * in {@code ksy} file) automatically read its content from stream, or that must
+     * be performed manually by calling generated {@code _read()}, {@code _readBE()}
+     * or {@code _readLE()} method.
+     *
+     * @return {@code true}, if generated {@code _read()} method invoked automatically
+     *         by class constructors and {@code false}, if it must be called explicitly
+     */
+    boolean autoRead();
+    /**
+     * Documentation string, that attached to the type in {@code doc} language element.
+     *
+     * @return Documentation string for type. If documentation is missed, returns empty string
+     */
+    String doc();
+}

src/main/java/io/kaitai/struct/annotations/Instance.java

@@ -0,0 +1,54 @@
+/**
+ * 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.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation, that applied to fields, getters or setters that represents instance
+ * field from {@code instances} language element.
+ *
+ * @author Mingun
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD})
+public @interface Instance {
+    /**
+     * Original identifier ({@code id} key) from {@code ksy} file.
+     *
+     * @return Identifier, that can differ from instance name, if it clash with
+     *         Java reserved words. Can not be empty
+     */
+    String id();
+    /**
+     * Documentation string, that attached to the field in {@code doc} language element.
+     *
+     * @return Documentation string for field. If documentation is missed, returns empty string
+     */
+    String doc();
+}

src/main/java/io/kaitai/struct/annotations/Parameter.java

@@ -0,0 +1,60 @@
+/**
+ * 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.annotations;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation, that applied to fields, getters or setters that represents parameter
+ * from {@code params} language element.
+ *
+ * @author Mingun
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.FIELD, ElementType.METHOD})
+public @interface Parameter {
+    /**
+     * Original identifier ({@code id} key) from {@code ksy} file.
+     *
+     * @return Identifier, that can differ from parameter name, if it clash with
+     *         Java reserved words. Can not be empty
+     */
+    String id();
+    /**
+     * Index of parameter in sequence of parameters of the type
+     *
+     * @return 0-based index of parameter in {@code params} language element
+     */
+    int index();
+    /**
+     * Documentation string, that attached to the parameter in {@code doc} language element.
+     *
+     * @return Documentation string for parameter. If documentation is missed, returns empty string
+     */
+    String doc();
+}