improved reference, added a test

Author: raydac

.projectKnowledge/JBBP_Types.mmd

@@ -0,0 +1,261 @@
+Mind Map generated by NB MindMap plugin   
+> __version__=`1.0`,showJumps=`true`
+---
+
+# Fields
+
+## Primitive<br/>types
+
+### allowed types
+> fillColor=`#FF9999`
+
+
+#### bit\[:1\.\.7\]
+> fillColor=`#9999FF`
+
+
+##### by default <br/>is 1 bit
+> fillColor=`#FF66FF`
+
+
+#### bool
+> fillColor=`#9999FF`
+
+
+##### 8 bit field
+> fillColor=`#99FFFF`
+
+
+###### FALSE \(==0\)
+> fillColor=`#CCFFCC`
+
+
+###### TRUE \(\!=0\)
+> fillColor=`#CCFFCC`
+
+
+#### byte
+> fillColor=`#9999FF`
+
+
+##### 8 bit signed field
+> fillColor=`#99FFFF`
+
+
+#### ubyte
+> fillColor=`#9999FF`
+
+
+##### 8 bit unsigned field
+> fillColor=`#99FFFF`
+
+
+#### short
+> fillColor=`#9999FF`
+
+
+##### 16 bit signed field
+> fillColor=`#99FFFF`
+
+
+#### ushort
+> fillColor=`#9999FF`
+
+
+##### 16 bit unsigned field
+> fillColor=`#99FFFF`
+
+
+#### int
+> fillColor=`#9999FF`
+
+
+##### 32 bit signed field
+> fillColor=`#99FFFF`
+
+
+#### long
+> fillColor=`#9999FF`
+
+
+##### 64 bit signed field
+> fillColor=`#99FFFF`
+
+
+### format
+> fillColor=`#FF9999`
+
+
+#### \<field\_type\> \[\<field\_name\>\];
+> fillColor=`#FFCC00`
+
+
+##### int;
+> fillColor=`#99FF99`
+
+
+##### int data;
+> fillColor=`#99FF99`
+
+
+## Complex types
+
+### Arrays
+> fillColor=`#9999FF`
+
+
+#### \<field\_type\> '\['\<array\_length\>|\<expression\>|\_'\]' \[\<array\_name\>\];
+> fillColor=`#FFCC00`,topicLinkUID=`152971A8B02A`
+
+
+##### \<array\_length\> is hardcoded <br/>number of items
+> fillColor=`#6666FF`,textColor=`#CCFFCC`
+
+
+###### bit:3 \[1244\];
+> fillColor=`#99FF99`
+
+
+##### \<expression\> is some expression<br/>provides length of the array
+> fillColor=`#6666FF`,textColor=`#CCFFCC`
+
+
+###### int length; byte \[length\*2\] data;
+> fillColor=`#99FF99`
+
+
+##### '\_' means read whole stream <br/>untill the stream end
+> fillColor=`#6666FF`,textColor=`#CCFFCC`
+
+
+###### It can be placed only<br/>for the end item in script
+> fillColor=`#FF3300`,textColor=`#FFFFFF`
+
+
+###### long header; byte \[\_\] allData;
+> fillColor=`#99FF99`
+
+
+### Structures
+> fillColor=`#9999FF`
+
+
+#### \[\<structure\_name\>\]\['\['array\_length|expression|\_'\]'\]\{ \<fields\>\.\.\. \}
+> fillColor=`#FFCC00`
+
+- TOPIC
+<pre>152971A8B02A</pre>
+
+##### \{bit;\}
+> fillColor=`#99FF99`
+
+
+##### header \{ubyte sections; ubyte datalen;\}<br/>sections \[header\.sections\]\{byte \[header\.datalen\] data;\}
+> fillColor=`#99FF99`
+
+
+## Special
+> leftSide=`true`
+
+
+### Align stream
+> fillColor=`#9999FF`
+
+
+#### align\[:number\_of\_bytes|\(expression\_in\_parentheses\)\]
+> fillColor=`#FFCC00`
+
+
+##### align; byte \[123\];
+> fillColor=`#99FF99`,leftSide=`true`
+
+
+##### align:4; byte\[123\];
+> fillColor=`#99FF99`,leftSide=`true`
+
+
+##### align:\($$\+45\); int data;
+> fillColor=`#99FF99`,leftSide=`true`
+
+
+#### by default<br/>align to 1 byte
+> fillColor=`#FF66FF`
+
+
+#### Skips bytes to align the byte<br/>counter to needed value
+> fillColor=`#FFFFCC`
+
+- TOPIC
+<pre>1529753E90BA</pre>
+
+### Byte counter
+> fillColor=`#FF9999`,topicLinkUID=`1529753E90BA`
+
+
+#### $$ in expressions
+> fillColor=`#FF9999`
+
+
+### Skip bytes
+> fillColor=`#9999FF`
+
+
+#### Skips needed number of bytes
+> fillColor=`#FFFFCC`
+
+- TOPIC
+<pre>1529753E90BA</pre>
+
+#### by default<br/>skip 1 byte
+> fillColor=`#FF66FF`
+
+
+#### skip\[:number\_of\_bytes|\(expression\_in\_parentheses\)\]
+> fillColor=`#FFCC00`
+
+
+##### skip; int;
+> fillColor=`#99FF99`
+
+
+##### skip:34; byte;
+> fillColor=`#99FF99`,leftSide=`true`
+
+
+##### skip:\($$\*2\); int data;
+> fillColor=`#99FF99`,leftSide=`true`
+
+
+## Byte order
+> leftSide=`true`
+
+
+### \[\<|\>\]\<filed\_type\>\.\.\.
+> fillColor=`#FFCC33`
+
+
+#### \>
+> fillColor=`#FF99FF`
+
+
+##### Big\-Endinan
+
+###### \>int \[26\] data;
+> fillColor=`#99FF99`
+
+
+##### It is the default value and<br/>can be omitted
+> fillColor=`#FF6666`
+
+
+#### \<
+> fillColor=`#FF99FF`
+
+
+##### Little\-Endian
+> leftSide=`true`
+
+
+###### \<long data;
+> fillColor=`#99FF99`
+

README.md

@@ -40,19 +40,22 @@ Change log
 
 Compatibility
 =============
-The Framework supports Java platform since Java SE 1.5+, its inside mapping mechanism developed in such manner to be compatible and with Android platform (as of Android 2.0) so that the framework is also Android compatible one (2.0+). It doesn't use any NIO and usage of the non-standard sun.misc.unsafe class is isolated through reflection mechanism. The Library doesn't have any external dependencies.
+The Framework is compatible with:
+* Java 1.5+
+* Android 2.0+
+For mapping sometime it uses reflection.
 
-How to use with Maven
+Maven dependency
 ======================
-The Framework is published in the Maven Central thus it can be added as a dependency into a project
+The Framework is published in the Maven Central and can be easily added as a dependency into a maven project
 ```
 <dependency>
   <groupId>com.igormaznitsa</groupId>
   <artifactId>jbbp</artifactId>
   <version>1.2.0</version>
 </dependency>
 ```
-also the precompiled jar, javadoc and sources can be downloaded manually from [the Maven central.](http://search.maven.org/#browse|808871750) 
+the precompiled library jar, javadoc and sources also can be downloaded directly from [the Maven central.](http://search.maven.org/#browse|808871750) 
 
 Hello world
 ============
@@ -104,40 +107,9 @@ The Example will print in console the text below
 ; END : Flags
 ;--------------------------------------------------------------------------------
 ```
-Format of a field
+Fields
 ==================
-Each field can be just a field or an array of fields, also it can be anonymous one or named one.
-
-    [<|>]field_type [[array_size|expression|_]] [field_name] ; 
-
-The first char shows the byte order to be used for parsing of the field (if the field is a multi-byte one) and can be omitted (and in the case the default order for the parser will be used). The Parser allows to parse a field as Big-Endinan one (for '>' prefix, it is the default state so that it can be omitted) and Little-Endian one (for '<' prefix). [You can read about endianness in wikipedia.](http://en.wikipedia.org/wiki/Endianness)
-
-**The Field name will be normalized to its lower-case representation, so that keep in your mind that names are case insensitive.**
-
-Supported data types and commands
-==================================
-- **bit[:(number_of_bits|expression_in_parentheses)]** - a bit field of fixed size (1..7 bits), by default 1
-- **byte** - a signed byte field (8 bits)
-- **ubyte** - a unsigned byte field (8 bits)
-- **bool** - a boolean field (1 byte)
-- **short** - a signed short field (2 bytes)
-- **ushort**- a unsigned short field (2 bytes)
-- **int** - an integer field (4 bytes)
-- **long** - a long field (8 bytes)
-- **align[:(number_of_bytes|expression_in_parentheses)]** - align the counter for number of bytes, by default 1. NB: It works relative to the current read byte counter!
-- **skip[:(number_of_bytes|expression_in_parentheses)]** - skip number of bytes, by default 1
-- **var[:(numeric_value|expression_in_parentheses)]** - a var field which should be read through an external processor defined by the user
-- **reset$$** - reset the input stream read byte counter, it is very useful for relative alignment operations   
-
-__expression_in_parentheses - means (expression)__
-
-Structures
-===========
-Fields can be collected in structures, the format of structure definition: 
-```
-[structure_name] [[array_size|expression|_]] { fields... } 
-```
-Structures can contain another structures and every field inside a structure has path in the format ***structure_name.field_name*** but if you want use field names inside the same structure then use their names without name of structure. 
+![JBBP field format, types and examples](https://github.com/raydac/java-binary-block-parser/blob/master/docs/jbbp_fields.png)
 
 Expressions
 ============

docs/jbbp_fields.png

@@ -27,7 +27,6 @@
 import java.io.EOFException;
 import java.io.IOException;
 import static org.junit.Assert.*;
-import org.junit.Ignore;
 import org.junit.Test;
 
 public class JBBPParserTest {

src/test/java/com/igormaznitsa/jbbp/JBBPParserTest.java

@@ -210,4 +210,17 @@ public void testMapTo_Object() throws Exception {
     assertEquals(3, mapped.c);
   }
 
+  @Test
+  public void testInterStructFieldReferences() throws Exception {
+    final JBBPParser parser = JBBPParser.prepare("header {ubyte sections; ubyte datalen;} sections [header.sections]{byte[header.datalen] data;}");
+    
+    final JBBPFieldArrayStruct sections = parser.parse(new byte[]{3, 2, 1, 2, 3, 4, 5, 6}).findFieldForNameAndType("sections", JBBPFieldArrayStruct.class);
+    assertEquals(3, sections.size());
+    for(int i=0;i<3;i++){
+      JBBPFieldArrayByte data = sections.getElementAt(i).findFieldForNameAndType("data", JBBPFieldArrayByte.class);
+      final int base = i*2;
+      assertArrayEquals(new byte []{(byte)(base+1), (byte)(base+2)}, data.getArray());
+    }
+  }
+  
 }