Merge pull request #470 from brendanzab/rename-array-formats

Rename array formats to `repeat_len{8|16|32|64}`

Author: brendanzab

README.md

@@ -25,7 +25,7 @@ def pixel = {
 def main = {
     width <- u16le,
     height <- u16le,
-    pixels <- array16 (width * height) pixel,
+    pixels <- repeat_len16 (width * height) pixel,
 };
 ```
 

doc/reference.md

@@ -27,8 +27,8 @@ elaboration, and core language is forthcoming.
   - [Conditional formats](#conditional-formats)
   - [Overlap formats](#overlap-formats)
   - [Number formats](#number-formats)
-  - [Array formats](#array-formats)
-  - [Repeat formats](#repeat-formats)
+  - [Exact-length repetition formats](#exact-length-repetition-formats)
+  - [Repeat until end formats](#repeat-until-end-formats)
   - [Limit formats](#limit-formats)
   - [Stream position formats](#stream-position-formats)
   - [Link formats](#link-formats)
@@ -140,7 +140,7 @@ If no binding is found, names can refer to one of the built-in primitives:
 - `u8`, `u16be`, `u16le`, `u32be`, `u32le`, `u64be`, `u64le`
 - `s8`, `s16be`, `s16le`, `s32be`, `s32le`, `s64be`, `s64le`
 - `f32be`, `f32le`, `f64be`, `f64le`
-- `array8`, `array16`, `array32`, `array64`
+- `repeat_len8`, `repeat_len16`, `repeat_len32`, `repeat_len64`
 - `link8`, `link16`, `link32`, `link64`
 - `stream_pos`
 - `succeed`, `fail`
@@ -297,9 +297,9 @@ data-dependent formats. For example:
 ```fathom
 {
     len <- u32be,
-    data <- array32 len { x <- u32be, y <- u32be },
-    //               ▲
-    //               └─── type of `len` is `Repr u32be`
+    data <- repeat_len32 len { x <- u32be, y <- u32be },
+    //                   ▲
+    //                   └─── type of `len` is `Repr u32be`
 }
 ```
 
@@ -319,10 +319,10 @@ let unit : Format =
 ```
 
 No annotations needed in the following example, as the type can be inferred from
-the type of `array8`:
+the type of `repeat_len8`:
 
 ```fathom
-array8 3 {}
+repeat_len8 3 {}
 ```
 
 #### Tuple syntax for record formats
@@ -386,10 +386,10 @@ more convenient:
 
     ⋮
 
-    start_code <- array16 seg_count u16be,
-    id_delta <- array16 seg_count s16be,
-    //                  ▲
-    //                  └──── `seg_count` is used here
+    start_code <- repeat_len16 seg_count u16be,
+    id_delta <- repeat_len16 seg_count s16be,
+    //                       ▲
+    //                       └──── `seg_count` is used here
 }
 ```
 
@@ -431,12 +431,12 @@ because they might appear in the representation types of subsequent fields.
 
 Some some examples of record formats and their representations are:
 
-| format                                            | `Repr` format                          |
-| ------------------------------------------------- | -------------------------------------- |
-| `{ x <- f32le, y <- f32le }`                      | `{ x : F32, y : F32 }`                 |
-| `{ len <- u16be, data <- array16 len s8 }`        | `{ len : U16, data : Array16 len S8 }` |
-| `{ magic <- u32be where u32_eq magic "icns" }`    | `{ magic : U32 }`                      |
-| `{ let len = 4 : U32, data <- array32 len s8 }`   | `{ len : U32, data : Array32 len S8 }` |
+| format                                                | `Repr` format                          |
+| ----------------------------------------------------- | -------------------------------------- |
+| `{ x <- f32le, y <- f32le }`                          | `{ x : F32, y : F32 }`                 |
+| `{ len <- u16be, data <- repeat_len16 len s8 }`       | `{ len : U16, data : Array16 len S8 }` |
+| `{ magic <- u32be where u32_eq magic "icns" }`        | `{ magic : U32 }`                      |
+| `{ let len = 4 : U32, data <- repeat_len32 len s8 }`  | `{ len : U32, data : Array32 len S8 }` |
 
 ### Conditional formats
 
@@ -479,8 +479,8 @@ enriched with information that occurs later on in the stream:
 
 ```fathom
 overlap {
-    records0 : array16 len array_record0,
-    records1 : array16 len (array_record0 records0),
+    records0 : repeat_len16 len array_record0,
+    records1 : repeat_len16 len (array_record0 records0),
 }
 ```
 
@@ -535,36 +535,40 @@ corresponding host representation:
 | `f32be`, `f32le`  | `F32`         |
 | `f64be`, `f64le`  | `F64`         |
 
-### Array formats
+### Exact-length repetition formats
 
-There are four array formats, corresponding to the four [array types](#arrays):
+There are four length constrained repetition formats, corresponding to the four
+[array types](#arrays):
 
-- `array8 : U8 -> Format -> Format`
-- `array16 : U16 -> Format -> Format`
-- `array32 : U32 -> Format -> Format`
-- `array64 : U64 -> Format -> Format`
+- `repeat_len8 : U8 -> Format -> Format`
+- `repeat_len16 : U16 -> Format -> Format`
+- `repeat_len32 : U32 -> Format -> Format`
+- `repeat_len64 : U64 -> Format -> Format`
 
-#### Representation of array formats
+These formats will parse the specified number of elements, failing if one of
+those elements failed to parse, or if the end of the current binary stream was
+reached.
 
-The [representation](#format-representations) of the array formats preserve the
-lengths, and use the representation of the element formats as the element types
-of the host [array types](#array-types).
+#### Representation of exact-length repetition formats
 
-| format                 | `Repr` format                       |
-| ---------------------- | ----------------------------------- |
-| `array8 len format`    | `Array8 len (Repr format)`          |
-| `array16 len format`   | `Array16 len (Repr format)`         |
-| `array32 len format`   | `Array32 len (Repr format)`         |
-| `array64 len format`   | `Array64 len (Repr format)`         |
+The [representation](#format-representations) of the repetition formats preserve
+the lengths in a corresponding [array type](#array-types):
 
-### Repeat formats
+| format                      | `Repr` format                       |
+| --------------------------- | ----------------------------------- |
+| `repeat_len8 len format`    | `Array8 len (Repr format)`          |
+| `repeat_len16 len format`   | `Array16 len (Repr format)`         |
+| `repeat_len32 len format`   | `Array32 len (Repr format)`         |
+| `repeat_len64 len format`   | `Array64 len (Repr format)`         |
+
+### Repeat until end formats
 
 The `repeat_until_end` format repeats parsing the given format until the end of
 the current binary stream is reached:
 
 - `repeat_until_end : Format -> Format`
 
-#### Representation of repeat formats
+#### Representation of repeat until end formats
 
 Because the repeat format does not have a predefined length, it is
 [represented](#format-representations) as a dynamically sized

fathom/src/core.rs

@@ -383,14 +383,14 @@ def_prims! {
     FormatF64Be => "f64be",
     /// 64-bit, IEEE-754 floating point formats (little-endian).
     FormatF64Le => "f64le",
-    /// Array formats, with unsigned 8-bit indices.
-    FormatArray8 => "array8",
-    /// Array formats, with unsigned 16-bit indices.
-    FormatArray16 => "array16",
-    /// Array formats, with unsigned 32-bit indices.
-    FormatArray32 => "array32",
-    /// Array formats, with unsigned 64-bit indices.
-    FormatArray64 => "array64",
+    /// Repeat formats up to an unsigned 8-bit length.
+    FormatRepeatLen8 => "repeat_len8",
+    /// Repeat formats up to an unsigned 16-bit length.
+    FormatRepeatLen16 => "repeat_len16",
+    /// Repeat formats up to an unsigned 32-bit length.
+    FormatRepeatLen32 => "repeat_len32",
+    /// Repeat formats up to an unsigned 64-bit length.
+    FormatRepeatLen64 => "repeat_len64",
     /// Repeat a format until the length of the given parse scope is reached.
     FormatRepeatUntilEnd => "repeat_until_end",
     /// Limit the format to an unsigned 8-bit byte length.

fathom/src/core/binary.rs

@@ -425,10 +425,10 @@ impl<'arena, 'data> Context<'arena, 'data> {
             (Prim::FormatF32Le, []) => read_const(reader, span, read_f32le, Const::F32),
             (Prim::FormatF64Be, []) => read_const(reader, span, read_f64be, Const::F64),
             (Prim::FormatF64Le, []) => read_const(reader, span, read_f64le, Const::F64),
-            (Prim::FormatArray8, [FunApp(_, len), FunApp(_, format)]) => self.read_array(reader, span, len, format),
-            (Prim::FormatArray16, [FunApp(_, len), FunApp(_, format)]) => self.read_array(reader, span, len, format),
-            (Prim::FormatArray32, [FunApp(_, len), FunApp(_, format)]) => self.read_array(reader, span, len, format),
-            (Prim::FormatArray64, [FunApp(_, len), FunApp(_, format)]) => self.read_array(reader, span, len, format),
+            (Prim::FormatRepeatLen8, [FunApp(_, len), FunApp(_, format)]) => self.read_repeat_len(reader, span, len, format),
+            (Prim::FormatRepeatLen16, [FunApp(_, len), FunApp(_, format)]) => self.read_repeat_len(reader, span, len, format),
+            (Prim::FormatRepeatLen32, [FunApp(_, len), FunApp(_, format)]) => self.read_repeat_len(reader, span, len, format),
+            (Prim::FormatRepeatLen64, [FunApp(_, len), FunApp(_, format)]) => self.read_repeat_len(reader, span, len, format),
             (Prim::FormatRepeatUntilEnd, [FunApp(_,format)]) => self.read_repeat_until_end(reader, format),
             (Prim::FormatLimit8, [FunApp(_, limit), FunApp(_, format)]) => self.read_limit(reader, limit, format),
             (Prim::FormatLimit16, [FunApp(_, limit), FunApp(_, format)]) => self.read_limit(reader, limit, format),
@@ -448,7 +448,7 @@ impl<'arena, 'data> Context<'arena, 'data> {
         }
     }
 
-    fn read_array(
+    fn read_repeat_len(
         &mut self,
         reader: &mut BufferReader<'data>,
         span: Span,

fathom/src/core/prim.rs

@@ -97,10 +97,10 @@ impl<'arena> Env<'arena> {
         env.define_prim(FormatF32Le, &FORMAT_TYPE);
         env.define_prim(FormatF64Be, &FORMAT_TYPE);
         env.define_prim(FormatF64Le, &FORMAT_TYPE);
-        env.define_prim_fun(FormatArray8, [&U8_TYPE, &FORMAT_TYPE], &FORMAT_TYPE);
-        env.define_prim_fun(FormatArray16, [&U16_TYPE, &FORMAT_TYPE], &FORMAT_TYPE);
-        env.define_prim_fun(FormatArray32, [&U32_TYPE, &FORMAT_TYPE], &FORMAT_TYPE);
-        env.define_prim_fun(FormatArray64, [&U64_TYPE, &FORMAT_TYPE], &FORMAT_TYPE);
+        env.define_prim_fun(FormatRepeatLen8, [&U8_TYPE, &FORMAT_TYPE], &FORMAT_TYPE);
+        env.define_prim_fun(FormatRepeatLen16, [&U16_TYPE, &FORMAT_TYPE], &FORMAT_TYPE);
+        env.define_prim_fun(FormatRepeatLen32, [&U32_TYPE, &FORMAT_TYPE], &FORMAT_TYPE);
+        env.define_prim_fun(FormatRepeatLen64, [&U64_TYPE, &FORMAT_TYPE], &FORMAT_TYPE);
         env.define_prim_fun(FormatRepeatUntilEnd, [&FORMAT_TYPE], &FORMAT_TYPE);
         env.define_prim_fun(FormatLimit8, [&U8_TYPE, &FORMAT_TYPE], &FORMAT_TYPE);
         env.define_prim_fun(FormatLimit16, [&U16_TYPE, &FORMAT_TYPE], &FORMAT_TYPE);
@@ -619,10 +619,10 @@ pub fn repr(prim: Prim) -> Step {
         Prim::FormatF32Le => step!(_, [] => Spanned::empty(Arc::new(Value::prim(Prim::F32Type, [])))),
         Prim::FormatF64Be => step!(_, [] => Spanned::empty(Arc::new(Value::prim(Prim::F64Type, [])))),
         Prim::FormatF64Le => step!(_, [] => Spanned::empty(Arc::new(Value::prim(Prim::F64Type, [])))),
-        Prim::FormatArray8 => step!(env, [len, elem] => Spanned::empty(Arc::new(Value::prim(Prim::Array8Type, [len.clone(), env.format_repr(elem)])))),
-        Prim::FormatArray16 => step!(env, [len, elem] => Spanned::empty(Arc::new(Value::prim(Prim::Array16Type, [len.clone(), env.format_repr(elem)])))),
-        Prim::FormatArray32 => step!(env, [len, elem] => Spanned::empty(Arc::new(Value::prim(Prim::Array32Type, [len.clone(), env.format_repr(elem)])))),
-        Prim::FormatArray64 => step!(env, [len, elem] => Spanned::empty(Arc::new(Value::prim(Prim::Array64Type, [len.clone(), env.format_repr(elem)])))),
+        Prim::FormatRepeatLen8 => step!(env, [len, elem] => Spanned::empty(Arc::new(Value::prim(Prim::Array8Type, [len.clone(), env.format_repr(elem)])))),
+        Prim::FormatRepeatLen16 => step!(env, [len, elem] => Spanned::empty(Arc::new(Value::prim(Prim::Array16Type, [len.clone(), env.format_repr(elem)])))),
+        Prim::FormatRepeatLen32 => step!(env, [len, elem] => Spanned::empty(Arc::new(Value::prim(Prim::Array32Type, [len.clone(), env.format_repr(elem)])))),
+        Prim::FormatRepeatLen64 => step!(env, [len, elem] => Spanned::empty(Arc::new(Value::prim(Prim::Array64Type, [len.clone(), env.format_repr(elem)])))),
         Prim::FormatLimit8 => step!(env, [_, elem] => env.format_repr(elem)),
         Prim::FormatLimit16 => step!(env, [_, elem] => env.format_repr(elem)),
         Prim::FormatLimit32 => step!(env, [_, elem] => env.format_repr(elem)),

formats/edid.fathom

@@ -47,7 +47,7 @@ def chromacity_coordinates = {
 };
 
 def established_timing = {
-    mode_bitmap <- array8 3 u8,             // TODO: bit patterns
+    mode_bitmap <- repeat_len8 3 u8,         // TODO: bit patterns
 };
 
 def standard_timing_information : Format = {

formats/edid.snap

@@ -28,7 +28,7 @@ def chromacity_coordinates : Format = {
     white_x_msb <- u8,
     white_y_msb <- u8,
 };
-def established_timing : Format = { mode_bitmap <- array8 3 u8 };
+def established_timing : Format = { mode_bitmap <- repeat_len8 3 u8 };
 def standard_timing_information : Format = ();
 def main : Format = {
     header <- header,

formats/gif.fathom

@@ -29,8 +29,8 @@ def logical_screen_descriptor = {
 ///
 /// - [GIF89a Specification: Section 17](https://www.w3.org/Graphics/GIF/spec-gif89a.txt)
 def header = {
-    magic <- array8 3 u8,   // TODO: where magic == ascii "GIF"`,
-    version <- array8 3 u8,
+    magic <- repeat_len8 3 u8,   // TODO: where magic == ascii "GIF"`,
+    version <- repeat_len8 3 u8,
 };
 
 /// # Global Color Table Entry
@@ -50,7 +50,7 @@ def color_table_entry = {
 ///
 /// - [GIF89a Specification: Section 19](https://www.w3.org/Graphics/GIF/spec-gif89a.txt)
 def global_color_table (len : U16) = {
-    entries <- array16 len color_table_entry,
+    entries <- repeat_len16 len color_table_entry,
 };
 
 def main = {

formats/gif.snap

@@ -6,10 +6,13 @@ def logical_screen_descriptor : Format = {
     bg_color_index <- u8,
     pixel_aspect_ratio <- u8,
 };
-def header : Format = { magic <- array8 3 u8, version <- array8 3 u8 };
+def header : Format = {
+    magic <- repeat_len8 3 u8,
+    version <- repeat_len8 3 u8,
+};
 def color_table_entry : Format = { red <- u8, green <- u8, blue <- u8 };
 def global_color_table : U16 -> Format = fun len => {
-    entries <- array16 len color_table_entry,
+    entries <- repeat_len16 len color_table_entry,
 };
 def main : Format = { header <- header, screen <- logical_screen_descriptor };
 '''

formats/ideas/ico.fathom

@@ -24,7 +24,7 @@ def image = {
 
 def main = {
     // NOTE: Could be useful to have invertible patterns here?
-    magic <- array8 4 u8 match {
+    magic <- repeat_len8 4 u8 match {
         [0, 0, 1, 0] => icon,   // TODO
         [0, 0, 2, 0] => cursor, // TODO
     },