alloy-sol-type-parser 0.8.11

Simple and light-weight Solidity type strings parser
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

# alloy-sol-type-parser

Simple and light-weight Solidity type strings parser.

This library is primarily a dependency for the user-facing APIs in
[`alloy-json-abi`] and [`alloy-dyn-abi`]. Please see the documentation for
those crates for more information.

This parser generally follows the [Solidity spec], however, it supports only a
subset of possible types, chosen to support ABI coding.

[Solidity spec]: https://docs.soliditylang.org/en/latest/grammar.html#a4.SolidityParser.typeName
[`alloy-json-abi`]: https://docs.rs/alloy-json-abi/latest/alloy_json_abi/
[`alloy-dyn-abi`]: https://docs.rs/alloy-dyn-abi/latest/alloy_dyn_abi/

### Usage

The `TypeSpecifier` is the top-level type in this crate. It is a wrapper around
a section of a string (called a `span`). It progressively breaks the strings
down into subspans, and adds metadata about the type. E.g. it tracks the stem
type as well as the sizes of array dimensions. A `TypeSpecifier` is expected to
handle any valid Solidity type string.

```rust
use alloy_sol_type_parser::TypeSpecifier;
use core::num::NonZeroUsize;

// Parse a type specifier from a string
let my_type = TypeSpecifier::parse("uint8[2][]").unwrap();

// Read the total span
assert_eq!(
    my_type.span(),
    "uint8[2][]"
);

// A type specifier has a stem type. This is the type string, stripped of its
// array dimensions.
assert_eq!(my_type.stem.span(), "uint8");

// Arrays are represented as a vector of sizes. This allows for deep nesting.
assert_eq!(
    my_type.sizes,
    // `None` is used for dynamic sizes. This is equivalent to `[2][]`
    vec![NonZeroUsize::new(2), None]
);

// Type specifiers also work for complex tuples!
let my_tuple = TypeSpecifier::parse("(uint8,(uint8[],bool))[39]").unwrap();
assert_eq!(
    my_tuple.stem.span(),
    "(uint8,(uint8[],bool))"
);

// Types are NOT resolved, so you can parse custom structs just by name.
let my_struct = TypeSpecifier::parse("MyStruct").unwrap();
```

### Why not support `parse()`?

The `core::str::FromStr` trait is not implemented for `TypeSpecifier` because
of lifetime constraints. Unfortunately, it is impossible to implement this for
a type with a lifetime dependent on the input str. Instead, we recommend using
the `parse` associated functions, or `TryFrom::<&str>::try_from` if a trait is
needed.

### Why not use `syn`?

This is NOT a full syntax library, and is not intended to be used as a
replacement for [`syn-solidity`]. This crate is intended to be used for
parsing type strings present in existing ecosystem tooling, and nothing else.
It is not intended to be used for parsing Solidity source code.

This crate is useful for:

- syntax-checking JSON ABI files
- providing known-good input to [`alloy-dyn-abi`]
- porting ethers.js code to rust

It is NOT useful for:

- parsing Solidity source code
- generating Rust code from Solidity source code
- generating Solidity source code from rust code

[`syn-solidity`]: https://docs.rs/syn-solidity/latest/syn_solidity/