ink_ir/ir/item/
storage.rs

1// Copyright (C) Use Ink (UK) Ltd.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use crate::{
16    ir,
17    ir::utils,
18};
19use proc_macro2::Ident;
20use syn::spanned::Spanned as _;
21
22/// An ink! storage struct definition.
23///
24/// Noticed by ink! through the `#[ink(storage)]` annotation.
25///
26/// # Note
27///
28/// An ink! smart contract must have exactly one storage definition.
29/// The storage definition must be found in the root of the ink! module.
30///
31/// # Example
32///
33/// ```
34/// # <ink_ir::Storage as TryFrom<syn::ItemStruct>>::try_from(syn::parse_quote! {
35/// #[ink(storage)]
36/// pub struct MyStorage {
37///     my_value: bool,
38///     counter: u32,
39/// }
40/// # }).unwrap();
41/// ```
42#[derive(Debug, PartialEq, Eq)]
43pub struct Storage {
44    /// The underlying `struct` Rust item.
45    ast: syn::ItemStruct,
46}
47
48impl quote::ToTokens for Storage {
49    /// We mainly implement this trait for this ink! type to have a derived
50    /// [`Spanned`](`syn::spanned::Spanned`) implementation for it.
51    fn to_tokens(&self, tokens: &mut proc_macro2::TokenStream) {
52        self.ast.to_tokens(tokens)
53    }
54}
55
56impl Storage {
57    /// Returns `true` if the first ink! annotation on the given struct is
58    /// `#[ink(storage)]`.
59    ///
60    /// # Errors
61    ///
62    /// If the first found ink! attribute is malformed.
63    pub(super) fn is_ink_storage(
64        item_struct: &syn::ItemStruct,
65    ) -> Result<bool, syn::Error> {
66        if !ir::contains_ink_attributes(&item_struct.attrs) {
67            return Ok(false)
68        }
69        // At this point we know that there must be at least one ink!
70        // attribute. This can be either the ink! storage struct,
71        // an ink! event or an invalid ink! attribute.
72        let attr = ir::first_ink_attribute(&item_struct.attrs)?
73            .expect("missing expected ink! attribute for struct");
74        Ok(matches!(attr.first().kind(), ir::AttributeArg::Storage))
75    }
76}
77
78impl TryFrom<syn::ItemStruct> for Storage {
79    type Error = syn::Error;
80
81    fn try_from(item_struct: syn::ItemStruct) -> Result<Self, Self::Error> {
82        let struct_span = item_struct.span();
83        let (_ink_attrs, other_attrs) = ir::sanitize_attributes(
84            struct_span,
85            item_struct.attrs,
86            &ir::AttributeArgKind::Storage,
87            |arg| {
88                match arg.kind() {
89                    ir::AttributeArg::Storage => Ok(()),
90                    _ => Err(None),
91                }
92            },
93        )?;
94        utils::ensure_pub_visibility("storage structs", struct_span, &item_struct.vis)?;
95        Ok(Self {
96            ast: syn::ItemStruct {
97                attrs: other_attrs,
98                ..item_struct
99            },
100        })
101    }
102}
103
104impl Storage {
105    /// Returns the non-ink! attributes of the ink! storage struct.
106    pub fn attrs(&self) -> &[syn::Attribute] {
107        &self.ast.attrs
108    }
109
110    /// Returns the identifier of the storage struct.
111    pub fn ident(&self) -> &Ident {
112        &self.ast.ident
113    }
114
115    /// Returns the generics of the storage struct.
116    pub fn generics(&self) -> &syn::Generics {
117        &self.ast.generics
118    }
119
120    /// Returns an iterator yielding all fields of the storage struct.
121    pub fn fields(&self) -> syn::punctuated::Iter<syn::Field> {
122        self.ast.fields.iter()
123    }
124}
125
126#[cfg(test)]
127mod tests {
128    use super::*;
129
130    #[test]
131    fn simple_try_from_works() {
132        let item_struct: syn::ItemStruct = syn::parse_quote! {
133            #[ink(storage)]
134            pub struct MyStorage {
135                field_1: i32,
136                field_2: bool,
137            }
138        };
139        assert!(Storage::try_from(item_struct).is_ok())
140    }
141
142    fn assert_try_from_fails(item_struct: syn::ItemStruct, expected: &str) {
143        assert_eq!(
144            Storage::try_from(item_struct).map_err(|err| err.to_string()),
145            Err(expected.to_string())
146        )
147    }
148
149    #[test]
150    fn conflicting_attributes_fails() {
151        assert_try_from_fails(
152            syn::parse_quote! {
153                #[ink(storage)]
154                #[ink(event)]
155                pub struct MyStorage {
156                    field_1: i32,
157                    field_2: bool,
158                }
159            },
160            "encountered conflicting ink! attribute argument",
161        )
162    }
163
164    #[test]
165    fn duplicate_attributes_fails() {
166        assert_try_from_fails(
167            syn::parse_quote! {
168                #[ink(storage)]
169                #[ink(storage)]
170                pub struct MyStorage {
171                    field_1: i32,
172                    field_2: bool,
173                }
174            },
175            "encountered duplicate ink! attribute",
176        )
177    }
178
179    #[test]
180    fn wrong_first_attribute_fails() {
181        assert_try_from_fails(
182            syn::parse_quote! {
183                #[ink(event)]
184                #[ink(storage)]
185                pub struct MyStorage {
186                    field_1: i32,
187                    field_2: bool,
188                }
189            },
190            "unexpected first ink! attribute argument",
191        )
192    }
193
194    #[test]
195    fn missing_storage_attribute_fails() {
196        assert_try_from_fails(
197            syn::parse_quote! {
198                pub struct MyStorage {
199                    field_1: i32,
200                    field_2: bool,
201                }
202            },
203            "encountered unexpected empty expanded ink! attribute arguments",
204        )
205    }
206
207    #[test]
208    fn non_pub_storage_struct() {
209        assert_try_from_fails(
210            syn::parse_quote! {
211                #[ink(storage)]
212                struct PrivateStorage {
213                    field_1: i32,
214                    field_2: bool,
215                }
216            },
217            "non `pub` ink! storage structs are not supported",
218        )
219    }
220}
ink_ir/ir/item/storage.rs

ink_ir/ir/item/
storage.rs
