criware_utf/
lib.rs

1/*!
2Implementation of the UTF table format used in CRIWARE CPK files.
3
4This crate primarily offers the [`utf_table`] macro, which automatically
5creates a table read and write procedure based on a schema provided as a
6struct definition (see the [`Table`] trait for more info on what is provided,
7and the macro itself for info on how to write the schema).
8
9```
10#[utf_table]
11struct Table {
12    #[column_name = "ColumnName"]
13    #[rowed]
14    rowed_value: i64,
15    #[constant]
16    constant_value: String,
17    #[optional]
18    #[rowed]
19    rowed_optional_value: i8,
20}
21```
22
23The [`Schema`] type (unrelated to `utf_table`) allows for retrieving
24the structure of a table *without its contents*. This can be useful
25for debugging, or any situation where a table may be one of many possible
26schemas (see example).
27
28The [`Reader`] and [`Writer`] types are also available for use in custom
29read/write procedures, but they are, in their current state, highly
30specialized for the [`utf_table`] macro, so using them is
31**not recommended**.
32
33# Examples
34
35This section demonstrates important features this crate provides. Each example
36can be dropped in to a project and compile (and run if you had the necessary
37table files).
38
39All of these examples demonstrate high-level functionality. For more precise
40examples and explanations, consult the page for the relevant type/macro.
41
42## Example: Basic table read/write
43```
44use criware_utf::{Table, utf_table};
45
46#[utf_table]
47struct ImportantTable {
48    #[column_name = "ID"]
49    id: i64,
50    file_name: String,
51    #[constant]
52    comment: String,
53}
54
55fn main() -> Result<(), Box<dyn std::error::Error>> {
56    let mut orig = std::fs::File::open("important-table.bin")?;
57    let mut new = std::fs::File::create("more-important-table.bin")?;
58    let mut table = ImportantTable::read(&mut orig)?;
59    for row in &table.rows {
60        println!("\"{}\" (id {})", row.file_name, row.id);
61    }
62    table.constants.comment = format!("\"{}\" -loser", table.constants.comment);
63    table.write(&mut new)?;
64    Ok(())
65}
66```
67
68## Example: Reading one of many schemas
69```
70use std::io::{Seek, SeekFrom};
71
72use criware_utf::{Schema, Table, utf_table};
73
74#[utf_table(table_name = "CoolTable")]
75struct CoolTableV1 {
76    id: i64,
77    name: String,
78}
79
80#[utf_table(table_name = "CoolTable")]
81struct CoolTableV2 {
82    id: i64,
83    name: String,
84    #[column_name = "Crc32"]
85    crc: u32,
86}
87
88enum CoolTable {
89    V1(CoolTableV1),
90    V2(CoolTableV2),
91}
92
93fn main() -> Result<(), Box<dyn std::error::Error>> {
94    let mut file = std::fs::File::open("table.bin")?;
95    let schema = Schema::read(&mut file)?;
96    let table = {
97        file.seek(SeekFrom::Start(0))?;
98        if schema.has_column("Crc32") {
99            CoolTable::V2(CoolTableV2::read(&mut file)?)
100        } else {
101            CoolTable::V1(CoolTableV1::read(&mut file)?)
102        }
103    };
104    // ... do something ...
105    Ok(())
106}
107```
108*/
109
110pub use criware_utf_core::*;
111
112#[macro_use]
113#[allow(unused_imports)]
114extern crate criware_utf_macros;
115
116pub use criware_utf_macros::utf_table;
criware_utf/lib.rs

criware_utf/
lib.rs
