a2lfile 3.1.0

read, modify and write a2l files
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# `a2lfile`

[![Github Actions](https://github.com/DanielT/a2lfile/actions/workflows/test.yml/badge.svg)](https://github.com/DanielT/a2lfile/actions)
[![codecov](https://codecov.io/gh/DanielT/a2lfile/branch/main/graph/badge.svg)](https://codecov.io/gh/DanielT/a2lfile)
[![license](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue)](#license)

`a2lfile` is a library that allows you to read, modify and write a2l files.

## Features

- full support for files using A2L version 1.7.1
- it is fast
- the layout and format of the input file is preserved. The intention is that after reading, modifying and then writing a file the resulting diff should be minimal
- easy access to application-specific data inside of IF_DATA blocks is provided through a macro that generates code based on an A2ML specification

## What is an a2l file

A2l files are commonly used during the development and testing of automotive ECUs.
The consumer of the a2l file typically performs online calibration over a protocol such as [XCP](https://en.wikipedia.org/wiki/XCP_(protocol)) and/or offline tuning by generating flashable parameter sets.

If you have never seen an a2l file then you are unlikely to need this library.

## Tools

The program [a2ltool](https://github.com/DanielT/a2ltool) is based on this library.

## Documentation

A simple program based on the `a2lfile` library might look like this:

```rust
use a2lfile::*;

fn main() {
    let input_filename = &std::ffi::OsString::from("example.a2l");
    let mut logmsgs = Vec::<A2LError>::new();
    let mut a2l_file = a2lfile::load(
        input_filename,
        None,
        &mut logmsgs,
        false
    ).expect("could not load the file");
    for log_msg in logmsgs {
        println!("warning while loading the file: {}", log_msg);
    }

    // perform a consistency check
    let mut logmsgs = Vec::<String>::new();
    a2l_file.check(&mut logmsgs);
    for log_msg in logmsgs {
        println!("warning during consistency check: {}", log_msg);
    }

    for measurement in &a2l_file.project.module[0].measurement {
        // do something with the MEASUREMENT objects in the file
        println!("MEASUREMENT: {:#?}", measurement);
    }

    // create a new CHARACTERISTIC object
    let new_characteristic = Characteristic::new(
        "my_name".to_string(),
        "my extended description".to_string(),
        CharacteristicType::Value,
        0x12345678,
        "something.RECORD_LAYOUT".to_string(),
        0.0,
        "NO_COMPU_METHOD".to_string(),
        0.0,
        100.0
    );
    a2l_file.project.module[0].characteristic.push(new_characteristic);


    // update the sorting to find a suitable insertion point for the new characteristic - by default it will be placed at the end
    a2l_file.sort_new_items();

    // write the modified file
    a2l_file.write(
        &std::ffi::OsString::from("example_output.txt"),
        Some("modified by the demo program")
    ).expect("failed to write output");
}

```

## Crate Features

All features are active by default. If "default-features = false" is set in Cargo.toml, then the following features can be enabled separately:

- `check`: perform a consistency check on the data
- `cleanup`: remove unused `GROUP`s, `RECORD_LAYOUT`s, `COMPU_METHOD`s, `COMPU_(V)TAB`s and `UNIT`s
- `ifdata_cleanup`: remove any `IF_DATA` blocks that could not be parsed using either the specification provided during load or the specification in the A2ML block in the file
- `merge`: merge two a2l files on the `MODULE` level
- `sort`: sort the data in the a2l file

## License

Licensed under either of

- Apache License, Version 2.0 ([`LICENSE-APACHE`](./LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([`LICENSE-MIT`](./LICENSE-MIT) or <http://opensource.org/licenses/MIT>)