factorio_api_gen/
schema.rs

1use serde::Deserialize;
2
3#[derive(Debug, Deserialize)]
4pub struct RuntimeApi {
5    pub application_version: String,
6    pub api_version: u32,
7    pub classes: Vec<Class>,
8    pub events: Vec<Event>,
9    pub defines: Vec<Define>,
10    pub global_objects: Vec<GlobalObject>,
11    #[serde(default)]
12    pub global_functions: Vec<Method>,
13    #[serde(default)]
14    pub concepts: Vec<Concept>,
15}
16
17#[derive(Debug, Deserialize)]
18pub struct Class {
19    pub name: String,
20    #[serde(default)]
21    pub description: String,
22    #[serde(default)]
23    pub r#abstract: bool,
24    #[serde(default)]
25    pub parent: Option<String>,
26    #[serde(default)]
27    pub methods: Vec<Method>,
28    #[serde(default)]
29    pub attributes: Vec<Attribute>,
30}
31
32#[derive(Debug, Deserialize)]
33pub struct Event {
34    pub name: String,
35    #[serde(default)]
36    pub description: String,
37    #[serde(default)]
38    pub filter: Option<String>,
39    #[serde(default)]
40    pub data: Vec<Parameter>,
41}
42
43#[derive(Debug, Deserialize)]
44pub struct Concept {
45    pub name: String,
46    #[serde(default)]
47    pub description: String,
48    #[serde(rename = "type")]
49    pub type_name: ApiType,
50}
51
52#[derive(Debug, Deserialize)]
53pub struct Define {
54    pub name: String,
55    #[serde(default)]
56    pub description: String,
57    #[serde(default)]
58    pub values: Vec<DefineValue>,
59    #[serde(default)]
60    pub subkeys: Vec<Define>,
61}
62
63#[derive(Debug, Deserialize)]
64pub struct DefineValue {
65    pub name: String,
66    #[serde(default)]
67    pub description: String,
68}
69
70#[derive(Debug, Deserialize)]
71pub struct GlobalObject {
72    pub name: String,
73    #[serde(default)]
74    pub description: String,
75    #[serde(rename = "type")]
76    pub type_name: ApiType,
77}
78
79#[derive(Debug, Deserialize)]
80pub struct Method {
81    pub name: String,
82    #[serde(default)]
83    pub description: String,
84    #[serde(default)]
85    pub parameters: Vec<Parameter>,
86    #[serde(default)]
87    pub return_values: Vec<Parameter>,
88    #[serde(default)]
89    pub format: MethodFormat,
90}
91
92#[derive(Debug, Default, Deserialize)]
93pub struct MethodFormat {
94    #[serde(default)]
95    pub takes_table: bool,
96}
97
98#[derive(Debug, Deserialize)]
99pub struct Attribute {
100    pub name: String,
101    #[serde(default)]
102    pub description: String,
103    #[serde(default)]
104    pub read_type: Option<ApiType>,
105    #[serde(default)]
106    pub write_type: Option<ApiType>,
107    #[serde(default)]
108    pub optional: bool,
109}
110
111#[derive(Debug, Deserialize)]
112pub struct Parameter {
113    #[serde(default)]
114    pub name: String,
115    #[serde(default)]
116    pub description: String,
117    #[serde(rename = "type")]
118    pub type_name: ApiType,
119    #[serde(default)]
120    pub optional: bool,
121}
122
123#[derive(Debug, Clone, Deserialize)]
124#[serde(transparent)]
125pub struct ApiType(pub serde_json::Value);
126
127impl ApiType {
128    pub fn as_simple_name(&self) -> Option<&str> {
129        self.0.as_str()
130    }
131
132    pub fn complex_type(&self) -> Option<&str> {
133        self.0.get("complex_type").and_then(|value| value.as_str())
134    }
135
136    pub fn child_type(&self, key: &str) -> Option<ApiType> {
137        self.0.get(key).cloned().map(ApiType)
138    }
139
140    pub fn options(&self) -> Vec<ApiType> {
141        self.0
142            .get("options")
143            .and_then(|value| value.as_array())
144            .map(|values| values.iter().cloned().map(ApiType).collect())
145            .unwrap_or_default()
146    }
147
148    /// Element types of a `tuple` complex type (from the `"values"` array).
149    pub fn tuple_values(&self) -> Vec<ApiType> {
150        self.0
151            .get("values")
152            .and_then(|v| v.as_array())
153            .map(|values| values.iter().cloned().map(ApiType).collect())
154            .unwrap_or_default()
155    }
156
157    /// For a `literal` complex type, returns the primitive kind: `"string"`,
158    /// `"number"`, or `"boolean"`, based on the JSON type of the `"value"` field.
159    ///
160    /// Returns `None` for non-literal types (e.g. `array`, `union`) even if they
161    /// happen to have a `"value"` key - the `complex_type` must be `"literal"`.
162    pub fn literal_kind(&self) -> Option<&'static str> {
163        // Guard: only `literal` complex types are valid here.
164        if self.complex_type() != Some("literal") {
165            return None;
166        }
167        let value = self.0.get("value")?;
168        if value.is_string() {
169            Some("string")
170        } else if value.is_number() {
171            Some("number")
172        } else if value.is_boolean() {
173            Some("boolean")
174        } else {
175            None
176        }
177    }
178
179    /// Parameters of a `table` complex type, as `(name, type, optional)` triples.
180    pub fn parameters(&self) -> Vec<(String, ApiType, bool)> {
181        self.0
182            .get("parameters")
183            .and_then(|value| value.as_array())
184            .map(|params| {
185                params
186                    .iter()
187                    .filter_map(|p| {
188                        let name = p.get("name")?.as_str()?.to_string();
189                        let ty = ApiType(p.get("type")?.clone());
190                        let optional = p.get("optional").and_then(|v| v.as_bool()).unwrap_or(false);
191                        Some((name, ty, optional))
192                    })
193                    .collect()
194            })
195            .unwrap_or_default()
196    }
197
198    /// Non-`nil` arms of a `union` complex type.
199    pub fn non_nil_options(&self) -> Vec<ApiType> {
200        self.options()
201            .into_iter()
202            .filter(|option| option.as_simple_name() != Some("nil"))
203            .collect()
204    }
205
206    /// Whether this type is a `union` whose non-nil arms are all string literals.
207    pub fn is_homog_string_literal_union(&self) -> bool {
208        if self.complex_type() != Some("union") {
209            return false;
210        }
211        let non_nil = self.non_nil_options();
212        !non_nil.is_empty()
213            && non_nil
214                .iter()
215                .all(|option| option.literal_kind() == Some("string"))
216    }
217
218    /// String values of a homogeneous string-literal union, in Factorio order.
219    ///
220    /// Returns an empty vec when this is not a homog string-literal union.
221    pub fn string_literal_values(&self) -> Vec<String> {
222        if !self.is_homog_string_literal_union() {
223            return Vec::new();
224        }
225        self.non_nil_options()
226            .into_iter()
227            .filter_map(|option| {
228                option
229                    .0
230                    .get("value")
231                    .and_then(|value| value.as_str())
232                    .map(str::to_string)
233            })
234            .collect()
235    }
236
237    /// Whether this union includes a `nil` arm.
238    pub fn union_has_nil(&self) -> bool {
239        self.complex_type() == Some("union")
240            && self
241                .options()
242                .iter()
243                .any(|option| option.as_simple_name() == Some("nil"))
244    }
245}
246
247#[cfg(test)]
248mod tests {
249    use super::ApiType;
250
251    fn parse(json: &str) -> ApiType {
252        ApiType(serde_json::from_str(json).expect("json"))
253    }
254
255    #[test]
256    fn detects_homog_string_literal_union() {
257        let ty = parse(
258            r#"{
259                "complex_type": "union",
260                "options": [
261                    {"complex_type": "literal", "value": "left"},
262                    {"complex_type": "literal", "value": "right"},
263                    "nil"
264                ]
265            }"#,
266        );
267        assert!(ty.is_homog_string_literal_union());
268        assert!(ty.union_has_nil());
269        assert_eq!(
270            ty.string_literal_values(),
271            vec!["left".to_string(), "right".to_string()]
272        );
273    }
274
275    #[test]
276    fn rejects_heterogeneous_union() {
277        let ty = parse(
278            r#"{
279                "complex_type": "union",
280                "options": ["LuaEntity", "LuaEquipment"]
281            }"#,
282        );
283        assert!(!ty.is_homog_string_literal_union());
284        assert!(ty.string_literal_values().is_empty());
285    }
286
287    #[test]
288    fn rejects_non_union() {
289        let ty = parse(r#""string""#);
290        assert!(!ty.is_homog_string_literal_union());
291    }
292}
factorio_api_gen/schema.rs

factorio_api_gen/
schema.rs
