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 [`Packet`] type mimics the method in which the primary tables in a CPK
29file are stored. Encryption and decryption are handled automatically.
30
31The [`Reader`] and [`Writer`] types are also available for use in custom
32read/write procedures, but they are, in their current state, highly
33specialized for the [`utf_table`] macro, so using them is
34**not recommended**.
35
36# Examples
37
38This section demonstrates important features this crate provides. Each example
39can be dropped in to a project and compile (and run if you had the necessary
40table files).
41
42All of these examples demonstrate high-level functionality. For more precise
43examples and explanations, consult the page for the relevant type/macro.
44
45## Example: Basic table read/write
46```
47use criware_utf::{Table, utf_table};
48
49#[utf_table]
50struct ImportantTable {
51    #[column_name = "ID"]
52    id: i64,
53    file_name: String,
54    #[constant]
55    comment: String,
56}
57
58fn main() -> Result<(), Box<dyn std::error::Error>> {
59    let mut orig = std::fs::File::open("important-table.bin")?;
60    let mut new = std::fs::File::create("more-important-table.bin")?;
61    let mut table = ImportantTable::read(&mut orig)?;
62    for row in &table.rows {
63        println!("\"{}\" (id {})", row.file_name, row.id);
64    }
65    table.constants.comment = format!("\"{}\" -loser", table.constants.comment);
66    table.write(&mut new)?;
67    Ok(())
68}
69```
70
71## Example: Reading one of many schemas
72```
73use std::io::{Seek, SeekFrom};
74
75use criware_utf::{Schema, Table, utf_table};
76
77#[utf_table(table_name = "CoolTable")]
78struct CoolTableV1 {
79    id: i64,
80    name: String,
81}
82
83#[utf_table(table_name = "CoolTable")]
84struct CoolTableV2 {
85    id: i64,
86    name: String,
87    #[column_name = "Crc32"]
88    crc: u32,
89}
90
91enum CoolTable {
92    V1(CoolTableV1),
93    V2(CoolTableV2),
94}
95
96fn main() -> Result<(), Box<dyn std::error::Error>> {
97    let mut file = std::fs::File::open("table.bin")?;
98    let schema = Schema::read(&mut file)?;
99    let table = {
100        file.seek(SeekFrom::Start(0))?;
101        if schema.has_column("Crc32") {
102            CoolTable::V2(CoolTableV2::read(&mut file)?)
103        } else {
104            CoolTable::V1(CoolTableV1::read(&mut file)?)
105        }
106    };
107    // ... do something ...
108    Ok(())
109}
110```
111*/
112
113pub use criware_utf_core::*;
114
115#[macro_use]
116#[allow(unused_imports)]
117extern crate criware_utf_macros;
118
119pub use criware_utf_macros::utf_table;
criware_utf/lib.rs

criware_utf/
lib.rs
