{"id":28498297,"url":"https://github.com/yanganto/toml-example","last_synced_at":"2025-07-03T16:30:57.067Z","repository":{"id":162516304,"uuid":"637042889","full_name":"yanganto/toml-example","owner":"yanganto","description":"A lib help generate toml example","archived":false,"fork":false,"pushed_at":"2025-06-27T02:29:12.000Z","size":72,"stargazers_count":5,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-27T02:41:37.274Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yanganto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-06T10:27:44.000Z","updated_at":"2025-06-27T02:29:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"ce859dbb-fc90-4062-a29f-903d09fdbd49","html_url":"https://github.com/yanganto/toml-example","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/yanganto/toml-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanganto%2Ftoml-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanganto%2Ftoml-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanganto%2Ftoml-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanganto%2Ftoml-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yanganto","download_url":"https://codeload.github.com/yanganto/toml-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yanganto%2Ftoml-example/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263360757,"owners_count":23454780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-08T13:37:10.936Z","updated_at":"2025-07-03T16:30:57.056Z","avatar_url":"https://github.com/yanganto.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Toml Example\n[![Crates.io][crates-badge]][crate-url]\n[![MIT licensed][mit-badge]][mit-url]\n[![Docs][doc-badge]][doc-url]\n\nA lib help generate toml example\n\n## Introduction\nThis crate provides the `TomlExample` trait and an accompanying derive macro.\n\nDeriving `TomlExample` on a struct will provide `to_example` function help generate toml example file base documentation\n- support `#[serde(default)]`, `#[serde(default = \"function_name\")]` attributes (`serde` feature, opt-in)\n- support `#[serde(rename)]`, `#[serde(rename_all = \"renaming rules\")]`, the renaming rules can be `lowercase`, `UPPERCASE`,\n`PascalCase`, `camelCase`, `snake_case`, `SCREAMING_SNAKE_CASE`, `kebab-case`, `SCREAMING-KEBAB-CASE`\n- provide `#[toml_example(default)]`, `#[toml_example(default = 0)]`, `#[toml_example(default = \"default_string\")]` attributes\n- The order matter of attribute macro, if `#[serde(default = ..]` and `#[toml_example(default = ..)]` existing at the same time with different value\n\n## Quick Example\n```rust \nuse toml_example::TomlExample;\n\n/// Config is to arrange something or change the controls on a computer or other device\n/// so that it can be used in a particular way\n#[derive(TomlExample)]\nstruct Config {\n    /// Config.a should be a number\n    a: usize,\n    /// Config.b should be a string\n    b: String,\n    /// Optional Config.c is a number\n    c: Option\u003cusize\u003e,\n    /// Config.d is a list of number\n    d: Vec\u003cusize\u003e,\n    /// Config.e should be a number\n    #[serde(default = \"default_int\")]\n    e: usize,\n    /// Config.f should be a string\n    #[serde(default = \"default_str\")]\n    f: String,\n    /// Config.g should be a number\n    #[toml_example(default =7)]\n    g: usize,\n    /// Config.f should be a string\n    #[toml_example(default = \"seven\")]\n    h: String,\n}\nfn default_int() -\u003e usize {\n    7\n}\nfn default_str() -\u003e String {\n    \"seven\".into()\n}\n\nConfig::to_toml_example(\"example.toml\");  // write example to a file\nlet example = Config::toml_example();\n```\n\nToml example base on the doc string of each field\n```toml\n# Config is to arrange something or change the controls on a computer or other device\n# so that it can be used in a particular way\n\n# Config.a should be a number\na = 0\n\n# Config.b should be a string\nb = \"\"\n\n# Optional Config.c is a number\n# c = 0\n\n# Config.d is a list of number\n# d = [ 0, ]\n\n# Config.e should be a number\ne = 7\n\n# Config.f should be a string\nf = \"seven\"\n\n# Config.g should be a number\ng = 7\n\n# Config.h should be a string\nh = \"seven\"\n\n```\n\n## Nesting Struct\nA nesting struct wrap with `Option\u003cT\u003e`, `Vec\u003cT\u003e`, `HashMap\u003cString, T\u003e`, `BTreeMap\u003cString, T\u003e` are handled.\nPlease add `#[toml_example(nesting)]`, or `#[toml_example(nesting = prefix)]` on the field.\n`#[toml_example(nesting)]`\n\n```rust\n  /// Service with specific port\n  #[derive(TomlExample)]\n  struct Service {\n      /// port should be a number\n      #[toml_example(default = 80)]\n      port: usize,\n  }\n  #[derive(TomlExample)]\n  #[allow(dead_code)]\n  struct Node {\n      /// Services are running in the node\n      #[toml_example(nesting)]\n      #[toml_example(default = http)]\n      services: HashMap\u003cString, Service\u003e,\n  }\n```\n`Node::toml_example()` will be following string.\n```toml\n# Services are running in the node\n# Service with specific port\n[services.http]\n# port should be a number\nport = 80\n\n```\nIf you want an optional field become a required field in example,\nplace the `#[toml_example(require)]` on the field.\nIf you want to skip some field you can use `#[toml_example(skip)]`,\nthe `#[serde(skip)]`, `#[serde(skip_deserializing)]` also works.\n```rust\nuse toml_example::TomlExample;\n#[derive(TomlExample)]\nstruct Config {\n    /// Config.a is an optional number\n    #[toml_example(require)]\n    a: Option\u003cusize\u003e,\n    /// Config.b is an optional string\n    #[toml_example(require)]\n    b: Option\u003cString\u003e,\n    #[toml_example(require)]\n    #[toml_example(default = \"third\")]\n    c: Option\u003cString\u003e,\n    #[toml_example(skip)]\n    d: usize,\n}\n```\n```toml\n# Config.a is an optional number\na = 0\n\n# Config.b is an optional string\nb = \"\"\n\nc = \"third\"\n\n```\n\n## Enum Field\nYou can also use fieldless enums, but you have to annotate them with `#[toml_example(enum)]` or\n`#[toml_example(is_enum)]` if you mind the keyword highlight you likely get when writing \"enum\".\nWhen annotating a field with `#[toml_example(default)]` it will use the [Debug](core::fmt::Debug) implementation.\nHowever for non-TOML datatypes like enums, this does not work as the value needs to be treated as a string in TOML.\nThe `#[toml_example(enum)]` attribute just adds the needed quotes around the [Debug](core::fmt::Debug) implementation\nand can be omitted if a custom [Debug](core::fmt::Debug) already includes those.\n\n```rust\nuse toml_example::TomlExample;\n#[derive(TomlExample)]\nstruct Config {\n    /// Config.priority is an enum\n    #[toml_example(default)]\n    #[toml_example(enum)]\n    priority: Priority,\n}\n#[derive(Debug, Default)]\nenum Priority {\n    #[default]\n    Important,\n    Trivial,\n}\nassert_eq!(Config::toml_example(),\nr#\"# Config.priority is an enum\npriority = \"Important\"\n\n\"#)\n```\n\n[crates-badge]: https://img.shields.io/crates/v/toml-example.svg\n[crate-url]: https://crates.io/crates/toml-example\n[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg\n[mit-url]: https://github.com/yanganto/toml-example/blob/readme/LICENSE\n[doc-badge]: https://img.shields.io/badge/docs-rs-orange.svg\n[doc-url]: https://docs.rs/toml-example/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyanganto%2Ftoml-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyanganto%2Ftoml-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyanganto%2Ftoml-example/lists"}