glossa-shared 0.0.8

# glossa-shared

[![glossa-shared.crate](https://img.shields.io/crates/v/glossa-shared.svg?logo=rust&logoColor=lightsalmon&label=glossa-shared)](https://crates.io/crates/glossa-shared)

[![Documentation](https://docs.rs/glossa-shared/badge.svg)](https://docs.rs/glossa-shared)
[![Apache-2 licensed](https://img.shields.io/crates/l/glossa-shared.svg?logo=apache)](../License)

<details>
<summary>
<a href="Readme-zh.md">
<img alt="Language/语言" src="./svg/language.svg"/>
</a>
</summary>

- en: English
- [zh: 中文](Readme-zh.md)
- [zh-Hant: 繁體中文](Readme-zh-Hant.md)

</details>

<details open>
<summary>
<img alt="Table of Contents" src="./svg/toc/toc.svg" />
</summary>

- [Design Goals](#design-goals)
- [Features](#features)
- [Data Types](#data-types)
  - [PHF Types](#phf-types)
  - [Map](#map)
- [Decode bincode](#decode-bincode)
  - [`decode::slice`](#decodeslice)
  - [`decode::file`](#decodefile)

</details>

## Design Goals

- Provide data types for code generated by `glossa-codegen`
- Decode(deserialize) bincode files generated by `glossa-codegen`

## Features

Q: Which features do I need to enable?
A:
**This depends on the type of code generated by `glossa-codegen`:**

| Codegen Method       | Required glossa-shared Feature          |
| -------------------- | --------------------------------------- |
| `.output_phf()`      | `["phf"]`                               |
| `.output_bincode()`  | `["std", "decode"]`                     |
| `.output_match_fn()` | *No need to import glossa-shared crate* |

---

## Data Types

### PHF Types

| Type                 | Description                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------- |
| `PhfL10nOrderedMap`  | Return type of functions generated by `.output_phf()`                                        |
| `PhfL10nAllInOneMap` | Return type of functions generated by `.output_phf_all_in_one()`                             |
| `PhfTupleKey`        | Tuple struct `(MapName, Key)`<br>Key type for maps from `.output_phf()`                      |
| `PhfTripleKey`       | Tuple struct `(Language, MapName, Key)`<br>Key type for maps from `.output_phf_all_in_one()` |

### Map

> NonDSL: Regular|Highlight|RegularAndHighlight

- L10nFlattenMap
  - `<(MapName, Key), Value>`
  - `output_bincode(NonDSL)` => `{language}`.bincode => Decode => L10nFlattenMap
- L10nMaps
  - `<Language, L10nFlattenMap>`
  - `output_bincode_all_in_one(NonDSL)` => all.bincode => Decode => L10nMaps
- L10nDSLMap
  - `<MapName, Resolver>`
  - `output_bincode(DSL)` => `{language}`.bincode => Decode => L10nDSLMap
- DSLMaps
  - `<Language, L10nDSLMap>`
  - `output_bincode_all_in_one(DSL)` => all.bincode => Decode => DSLMaps

## Decode bincode

- `decode::slice` does not require "std" feature
- `decode::file` requires "std"

### `decode::slice`

- decode_slice()
  - decode_single_data_to_map()
  - `output_bincode(NonDSL)` => `{language}`.bincode => Read => `&[u8]` => `decode_single_data_to_map(&[u8])` => `<(MapName, Key), Value>`
  - decode_to_maps()
    - `output_bincode_all_in_one(NonDSL)` => all.bincode => Read => `&[u8]` => `decode_to_maps(&[u8])` => `<Language, L10nFlattenMap>`
  - decode_single_data_to_dsl_map()
    - `output_bincode(DSL)` => `{language}`.bincode => Read => `&[u8]` => `decode_single_data_to_dsl_map(&[u8])` => `<MapName, Resolver>`
  - decode_to_dsl_maps
    - `output_bincode_all_in_one(DSL)` => all.bincode => Read => `&[u8]` => `decode_to_dsl_maps(&[u8])` => `<Language, <MapName, Resolver>>`

### `decode::file`

- decode_file()
  - decode_single_file_to_flatten_map()
    - `output_bincode(NonDSL)` => `{language}`.bincode => `decode_single_file_to_flatten_map({language}.bincode)` => `<(MapName, Key), Value>`
  - decode_file_to_maps()
    - `output_bincode_all_in_one(NonDSL)` => all.bincode => `decode_file_to_maps("all.bincode")` => `<Language, L10nFlattenMap>`
  - decode_single_file_to_dsl_map()
    - `output_bincode(DSL)` => `{language}`.bincode => `decode_single_file_to_dsl_map({language}.bincode)` => `<MapName, Resolver>`
  - decode_file_to_dsl_maps()
    - `output_bincode_all_in_one(DSL)` => all.bincode => `decode_file_to_dsl_maps("all.bincode")` => `<Language, <MapName, Resolver>>`