rework API to use implement Iterator

this completely revamps the API. the `parse` function is gone, instead
you now construct a new `Parser` using `Parser::new` and then use the
iterator API on it which will yield a `next` until the whole input has
been parsed.

due to this there's now no longer a need to return a list of values from
the API as instead we return the individual events (or errors) step by
step. thus the dependency on `alloc` and `heapless` has been removed.

to get the same result as before (everything collected into a vector)
the `collect` API of `Iterator` can be used by consumers.

Author: rursprung

.github/workflows/CI.yml

@@ -14,12 +14,7 @@ jobs:
       fail-fast: false
       matrix:
         rust: [1.81.0, stable]
-        features: ['alloc', 'alloc,defmt', 'heapless', 'heapless,defmt']
-        exclude:
-          - rust: 1.81.0
-            features: 'alloc,defmt'
-          - rust: 1.81.0
-            features: 'heapless,defmt'
+        features: ['']
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -31,17 +26,17 @@ jobs:
       - name: Install required cargo components
         run: cargo +stable install clippy-sarif sarif-fmt
       - name: build
-        run: cargo build --features ${{ matrix.features }}
+        run: cargo build ${{ matrix.features }}
       - name: check
-        run: cargo check --features ${{ matrix.features }}
+        run: cargo check ${{ matrix.features }}
       - name: test
-        run: cargo test --features ${{ matrix.features }}
+        run: cargo test ${{ matrix.features }}
       - name: check formatting
         run: cargo fmt --all -- --check
       - name: audit
         run: cargo audit
       - name: clippy (lib)
-        run: cargo clippy --features ${{ matrix.features }} --message-format=json | clippy-sarif | tee rust-clippy-results.sarif | sarif-fmt
+        run: cargo clippy ${{ matrix.features }} --message-format=json | clippy-sarif | tee rust-clippy-results.sarif | sarif-fmt
         continue-on-error: true
       - name: Upload analysis results to GitHub
         uses: github/codeql-action/upload-sarif@v3

CHANGELOG.md

@@ -10,7 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * `Copy`, `Clone` and `Hash` on error & event types (where possible)
 ### Changed
 * The MSRV has been updated to 1.81.0 due to `core::error::Error` being implemented
-* **BREAKING**: the features `use_alloc` and `use_heapless` have been renamed to `alloc` and `heapless` respectively.
+* **BREAKING**: The `parse` API has been replaced with `Parser::new` where `Parser` now implements `Iterator` and the `next` function returns each parsed command
+  * Accordingly, the features `use_alloc` and `use_heapless` have been removed.
 
 ## [0.2.0] - 2023-11-14
 ### Added

Cargo.toml

@@ -12,18 +12,14 @@ license = "MIT OR Apache-2.0"
 
 [dependencies]
 defmt = { version = "0.3", optional = true }
-heapless = { version = "0.8", optional = true }
 
 rgb = { version = "0.8", optional = true }
 serde = { version = "1.0", features = ["derive"], optional = true }
 
 [features]
 default = ["accelerometer_event", "button_event", "color_event", "gyro_event", "location_event", "magnetometer_event", "quaternion_event"]
 
-heapless = ["dep:heapless"]
-alloc = []
-
-defmt = ["dep:defmt", "heapless?/defmt-03"]
+defmt = ["dep:defmt"]
 
 accelerometer_event = []
 button_event = []

README.md

@@ -9,12 +9,6 @@ which is e.g. used by the [Adafruit Bluefruit LE UART Friend](https://learn.adaf
 
 Note that this work is not affiliated with Adafruit.
 
-## Mandatory Features
-This crate is `no_std` and you can choose whether you want to use
-[`heapless::Vec`](https://docs.rs/heapless/0.8.0/heapless/struct.Vec.html) by selecting the feature `heapless` or
-[`alloc::vec::Vec`](https://doc.rust-lang.org/alloc/vec/struct.Vec.html) by selecting the feature `alloc`.
-If you select neither or both you'll get a compile error.
-
 ## Optional Features
 * `defmt`: you can enable the [`defmt`](https://defmt.ferrous-systems.com/) feature to get a `defmt::Format` implementation for all structs & enums and a `defmt::debug!` call for each command being parsed.
 * `rgb`: if enabled, `From<ColorEvent> for RGB8` is implemented to support the [RGB crate](https://crates.io/crates/rgb).
@@ -24,8 +18,8 @@ If you select neither or both you'll get a compile error.
   If other events are received, a `ProtocolParseError::DisabledControllerDataPackageType` will be returned.
 
 ## Usage
-The entry point to use this crate is the `parse` function. Note that this is a [sans I/O](https://sans-io.readthedocs.io/)
-crate, i.e. you have to talk to the Adafruit device, the `parse` function just expects a byte sequence.
+The entry point to use this crate is `Parser` which implements `Iterator` to access the events in the input.
+Note that this is a [sans I/O](https://sans-io.readthedocs.io/) crate, i.e. you have to talk to the Adafruit device, the parser just expects a byte sequence.
 
 ## Examples
 A simple example for the STM32F4 microcontrollers is [available](examples/stm32f4-event-printer/README.md).

examples/stm32f4-event-printer/Cargo.lock

@@ -17,7 +17,7 @@ defmt = "0.3.6"
 defmt-rtt = "0.4"
 
 # use `adafruit-bluefruit-protocol = "0.1"` in reality; path used here to ensure that the example always compiles against the latest master
-adafruit-bluefruit-protocol = { path = "../..", features = ["defmt", "heapless"] }
+adafruit-bluefruit-protocol = { path = "../..", features = ["defmt"] }
 
 [profile.release]
 codegen-units = 1

examples/stm32f4-event-printer/Cargo.toml

@@ -84,8 +84,10 @@ impl BluefruitLEUARTFriend {
             filled_buffer
         );
 
-        let event = adafruit_bluefruit_protocol::parse::<4>(filled_buffer);
-        defmt::info!("received event(s) over bluetooth: {}", &event);
+        let parser = adafruit_bluefruit_protocol::Parser::new(filled_buffer);
+        for event in parser {
+            defmt::info!("received event over bluetooth: {:?}", &event);
+        }
 
         // switch out the buffers
         filled_buffer.fill(0);