-
Notifications
You must be signed in to change notification settings - Fork 123
Add Typeshare2 Documentation #277
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| # typeshare-engine | ||
|
|
||
| This crate includes all of the actual implementations of typeshare functionality. It should be a dependency of anyone trying to USE typeshare as a library. It depends ONLY on typeshare-model, not on any language crates. It exports functions that make use of the trait in typeshare-model. | ||
| This crate includes all of the actual implementations of typeshare functionality. It should be a dependency of anyone trying to USE typeshare as a library. It exports functions that make use of the trait in typeshare-model. | ||
|
|
||
| Currently, the public API of typeshare-engine is considered fairly unstable. Feel free to use it, but we expect updates to usually be published as major versions. You only need to depend on `typeshare-engine` if you want to use typeshare as a _library_; if you're implementing your own language, you only need to depend on `typeshare-model`, and if you're creating a typeshare binary, you only also need `typeshare-driver`. | ||
| Currently, the public API of typeshare-engine is considered fairly unstable. Feel free to use it, but we expect updates to usually be published as major versions. You only need to depend on `typeshare-engine` if you want to use typeshare as a _library_; if you're implementing your own language, you only need to depend on [typeshare-model](../model), and if you're creating a typeshare binary, you only also need [typeshare-driver](../driver) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,3 @@ | ||
| # typeshare-model | ||
|
|
||
| This crate is the base dependency for almost everything else. It includes especially the types and traits necessary for a single language implementation (that is, typeshare-swift could depend ONLY on typeshare-model). It can include utility functionality that might be necessary for a language implementation, but ideally not much in the way of major implementation stuff. | ||
| This crate is the core dependency for all implementations of specific languages for typeshare. It defines the [`Language`](https://docs.rs/typeshare-model/latest/typeshare_model/trait.Language.html) trait, along with a handful of supporting types, which a language implementation must implement. Check out the official implementations for [Swift](../langs/swift/src/lib.rs), [Kotlin](../langs/kotlin/src/lib.rs), and [Typescript](../langs/typescript/src/lib.rs) for examples. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,115 @@ | ||
| # Making your own typeshare | ||
|
|
||
| Typeshare is designed to make it easy to implement your own languages as a separate binary. This document provides a basic walkthrough for how to create your own langauge implementation. | ||
|
|
||
| ## Project Structure | ||
|
|
||
| There are two key components to making your own Typeshare implementation: | ||
| - `typeshare-model` | ||
| - `typeshare-driver` | ||
|
|
||
| In a typical Typeshare project, each language implementation will be its own crate, with the `typeshare-driver` bringing your implementations together into a single CLI binary. | ||
|
|
||
| ``` | ||
| typeshare-binary | ||
| ├── typeshare-language-1 | ||
| │ ├── src | ||
| │ │ └── lib.rs | ||
| │ └── cargo.toml | ||
| ├── typeshare-language-2 | ||
| │ ├── src | ||
| │ │ └── lib.rs | ||
| │ └── cargo.toml | ||
| ├── src | ||
| │ └── main.rs | ||
| └── cargo.toml | ||
| ``` | ||
|
|
||
| ## Start the Project | ||
|
|
||
| Set up the binary: | ||
|
|
||
| ```bash | ||
| cargo new my-typeshare-binary | ||
| cd my-typeshare-binary | ||
| ``` | ||
|
|
||
| This is where the `typeshare-driver`'s main macro for setting up the binary will be. Add the `typeshare-driver` dependency | ||
| ```bash | ||
| cargo add typeshare-driver | ||
| ``` | ||
| You will also need to add the dependency `log` | ||
|
|
||
| ```bash | ||
| cargo add log | ||
| ``` | ||
|
|
||
| Add a crate for your language implementation (or as many as you want! Up to 16): | ||
| ```bash | ||
| cargo new my-typeshare-language --lib | ||
| cd my-typeshare-language | ||
| ``` | ||
| Once you have your language crate, add the `typeshare-model` dependency: | ||
|
|
||
| ```bash | ||
| cargo add typeshare-model | ||
| ``` | ||
| Some other dependencies you will need to implement your own language include: | ||
| - `thiserror` | ||
| - `serde` with the feature `derive` | ||
| - `joinery` | ||
| - `itertools` | ||
| - `anyhow` | ||
|
|
||
| So make sure to add these to your language crate as well | ||
|
|
||
| ## Implementing a Language | ||
|
|
||
| Once your project is set up, you need to implement the Language trait from `typeshare-model` inside your langugae crate. | ||
|
|
||
| There a few functions that have to be implemented: | ||
| - `new_from_config`: This instantiates your language struct using configuration from a `typeshare.toml` file or the command line | ||
| - `output_filename_for_crate`: This is used in multi-file mode for setting up consistent naming for the files. | ||
| - `write_*`: These functions are your implementations of how various types should be handled. These implementations should typically call `format_type`, which is used to format Rust types into strings for writing to the Typeshare generated file. | ||
| - `format_special_type`: This is where you add custom implementations of special types for each language that is called from within `format_type`. | ||
|
|
||
| Additional functions that are optional but common to implement include: | ||
| - `mapped_type`: This allows you to create specific custom handling for specific types. | ||
| - `begin_file`, `end_file`, `write_additional_files` to add other per-file or per-directory handling, such as information about the file generation in comments at the top of the file, or other custom handling. | ||
|
|
||
| See the function documentation for more detailed information and look through our implementations of Typeshare for [Kotlin](../../app/langs/kotlin/), [Swift](../../app/langs/swift/), and [Typescript](../../app/langs/typescript/) for examples. | ||
|
|
||
| Once the Language trait has been implemented, your Typeshare is ready to be built! | ||
|
|
||
| ## Building Your Typeshare | ||
|
|
||
| In `main.rs` once your language has been implemented, all you have to do is pass them into the `typeshare_driver` macro: | ||
| ```rust | ||
| use typeshare_driver::typeshare_binary; | ||
| use typeshare_language_1::YourLanguage1; | ||
| use typeshare_language_2::YourLanguage2; | ||
|
|
||
| typeshare_binary! { YourLanguage1, YourLanguage2 } | ||
| ``` | ||
| Now, running `cargo build` will build your Typeshare with your language implementations and create a fully functional CLI tool. | ||
|
|
||
| ## Using Your Typeshare | ||
|
|
||
| In a project where you want to use Typeshare, add `typeshare` to your `cargo.toml` and add the Typeshare annotations to any types you want to share (see more about using annotations [here](./usage/annotations.md)). Set up a `typeshare.toml` at the root of your project with any configuration information for your implementation. | ||
|
|
||
| The general usage of a Typeshare CLI binary is: | ||
| ```bash | ||
| typeshare-binary --lang <your-language-1> --output-file <path-to-your-output-file> <path-to-directory-to-run-typeshare-on> | ||
| ``` | ||
| or | ||
| ```bash | ||
| typeshare-binary --lang <your-language-1> --output-folder <path-to-your-output-folder> <path-to-directory-to-run-typeshare-on> | ||
| ``` | ||
| depending if you want the generated code to be outputted into a folder or a file. | ||
|
|
||
| To run your Typeshare for multiple languages, you rerun the command with each desired language. | ||
|
|
||
| To see all possible languages in a Typeshare and learn about other possible commands run: | ||
| ```bash | ||
| typeshare-binary --help | ||
| ``` |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.