{"id":18956374,"url":"https://github.com/qedk/ini-rs","last_synced_at":"2025-04-18T15:02:11.159Z","repository":{"id":46790443,"uuid":"272625360","full_name":"QEDK/ini-rs","owner":"QEDK","description":"A simple macro utility built on top of configparser with no other dependencies built on Rust.","archived":false,"fork":false,"pushed_at":"2021-09-25T17:57:53.000Z","size":71,"stargazers_count":8,"open_issues_count":6,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T01:34:39.838Z","etag":null,"topics":["configuration","ini","macro","parser","rust","settings"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/QEDK.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-LGPL","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-16T06:16:02.000Z","updated_at":"2023-12-29T01:30:44.000Z","dependencies_parsed_at":"2022-09-16T04:12:16.278Z","dependency_job_id":null,"html_url":"https://github.com/QEDK/ini-rs","commit_stats":null,"previous_names":["qedk/ini-rs"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QEDK%2Fini-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QEDK%2Fini-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QEDK%2Fini-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QEDK%2Fini-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/QEDK","download_url":"https://codeload.github.com/QEDK/ini-rs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249509039,"owners_count":21283519,"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":["configuration","ini","macro","parser","rust","settings"],"created_at":"2024-11-08T13:52:21.276Z","updated_at":"2025-04-18T15:02:11.107Z","avatar_url":"https://github.com/QEDK.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ini\n[![Build Status](https://travis-ci.com/mexili/ini-rs.svg?branch=master)](https://travis-ci.com/mexili/ini-rs) [![Crates.io](https://img.shields.io/crates/l/ini?color=black)](LICENSE-MIT) [![Crates.io](https://img.shields.io/crates/v/ini?color=black)](https://crates.io/crates/ini) [![Released API docs](https://docs.rs/ini/badge.svg)](https://docs.rs/ini) [![Maintenance](https://img.shields.io/maintenance/yes/2020)](https://github.com/mexili/ini-rs)\n\nThis crate provides the `ini!` macro which implements a basic configuration language which provides a structure similar to what’s found in Windows' `ini` files. You can use this to write Rust programs which can be customized by end users easily.\n\nThis is a simple macro utility built on top of `configparser` with no other dependencies built on Rust. For more advanced functions, you should use the [configparser](https://crates.io/crates/configparser) crate.\n\n## Quick Start\n\nA basic `ini`-syntax file (we say ini-syntax files because the files don't need to be necessarily `*.ini`) looks like this:\n```INI\n[DEFAULT]\nkey1 = value1\npizzatime = yes\ncost = 9\n\n[topsecrets]\nnuclear launch codes = topsecret\n\n[github.com]\nUser = QEDK\n```\nEssentially, the syntax consists of sections, each of which can which contains keys with values.\n\n### Installation\nYou can install this easily via `cargo` by including it in your `Cargo.toml` file like:\n```TOML\n[dependencies]\nini = \"1.3.0\"\n```\n\n### The `ini!` macro\nThe `ini!` macro allows you to simply get a hashmap of type `HashMap\u003cString, HashMap\u003cString, Option\u003cString\u003e\u003e\u003e` for a list of files.\nIt is planned to provide shell expansion and file-writing in the future:\n```rust\n#[macro_use]\nextern crate ini;\n\nfn main() {\n  let map = ini!(\"...path/to/file\");\n  // Proceed to use normal HashMap functions on the map:\n  let val = map[\"section\"][\"key\"].clone().unwrap();\n\n  // To load multiple files, just do:\n  let (map1, map2, map3) = ini!(\"path/to/file1\", \"path/to/file2\", \"path/to/file3\");\n  // Each map is a cloned hashmap with no relation to other ones\n}\n```\nIf loading a file fails or the parser is unable to parse the file, the code will `panic` with an appropriate error. In case, you want to handle this\ngracefully, it's recommended you use the `safe` metavariable instead. This will make sure your code does not panic and instead exists as a\n`Result\u003cHashMap, String\u003e` type and let you deal with errors gracefully.\n```rust\nlet map = ini!(safe \"...path/to/file\");\n// Proceed to use normal HashMap functions on the map:\nlet val = map.unwrap()[\"section\"][\"key\"].clone().unwrap();\n// Note the extra unwrap here, which is required because our HashMap is inside a Result type.\n```\n\n### The `inistr!` macro\nThe `inistr!` macro allows you to simply get a hashmap of type `HashMap\u003cString, HashMap\u003cString, Option\u003cString\u003e\u003e\u003e` for a list of strings.\n```rust\n#[macro_use]\nextern crate ini;\n\nfn main() {\n  let configstring = \"[section]\n    key = value\n    top = secret\";\n  let map = inistr!(configstring);\n  // Proceed to use normal HashMap functions on the map:\n  let val = map[\"section\"][\"top\"].clone().unwrap();\n  // The type of the map is HashMap\u003cString, HashMap\u003cString, Option\u003cString\u003e\u003e\u003e\n  assert_eq!(val, \"secret\"); // value accessible!\n\n  // To load multiple string, just do:\n  let (map1, map2, map3) = inistr!(\u0026String::from(configstring), configstring,  \"[section]\n    key = value\n    top = secret\");\n  // Each map is a cloned hashmap with no relation to other ones\n}\n```\nIf loading a file fails or the parser is unable to parse the file, the code will `panic` with an appropriate error. In case, you want to handle this\ngracefully, it's recommended you use the `safe` metavariable instead. This will make sure your code does not panic and instead exists as a\n`Result\u003cHashMap, String\u003e` type and let you deal with errors gracefully.\n```rust\nlet map = inistr!(safe strvariable_or_strliteral);\n // Proceed to use normal HashMap functions on the map:\nlet val = map.unwrap()[\"section\"][\"key\"].clone().unwrap();\n // Note the extra unwrap here, which is required because our HashMap is inside a Result type.\n```\n\n## Supported datatypes\n`configparser` does not guess the datatype of values in configuration files and stores everything as strings, same applies to `ini`. If you need getters that parse the values for you, you might want to use the `configparser` crate instead. You can ofcourse just choose to parse the string values yourself.\n```rust\nlet my_string = map[\"section\"][\"key\"].clone().unwrap();\nlet my_int = my_string.parse::\u003ci32\u003e().unwrap();\n```\n\n## Supported `ini` file structure\nA configuration file can consist of sections, each led by a `[section-name]` header, followed by key-value entries separated by a `=`. By default, section names and key names are case-insensitive. All leading and trailing whitespace is removed from stored keys, values and section names.\nKey values can be omitted, in which case the key-value delimiter (`=`) may also be left out (but this is different from putting a delimiter, we'll\nexplain it later). You can use comment symbols (`;` and `#` to denote comments). Keep in mind that key-value pairs or section headers cannot span multiple lines.\nOwing to how ini files usually are, this means that `[`, `]`, `=`, `;` and `#` are special symbols (this crate will allow you to use `]` sparingly).\n\nLet's take for example:\n```INI\n[section headers are case-insensitive]\n[   section headers are case-insensitive    ]\nare the section headers above same? = yes\nsectionheaders_and_keysarestored_in_lowercase? = yes\nkeys_are_also_case_insensitive = Values are case sensitive\n;anything after a comment symbol is ignored\n#this is also a comment\nspaces in keys=allowed ;and everything before this is still valid!\nspaces in values=allowed as well\nspaces around the delimiter = also OK\n\n\n[All values are strings]\nvalues like this= 0000\nor this= 0.999\nare they treated as numbers? = no\nintegers, floats and booleans are held as= strings\n\n[value-less?]\na_valueless_key_has_None\nthis key has an empty string value has Some(\"\") =\n\n    [indented sections]\n        can_values_be_as_well = True\n        purpose = formatting for readability\n        is_this_same     =        yes\n            is_this_same=yes\n```\nAn important thing to note is that values with the same keys will get updated, this means that the last inserted key (whether that's a section header\nor property key) is the one that remains in the `HashMap`.\nThe only bit of magic the API does is the section-less properties are put in a section called \"default\".\n\n## License\n\nLicensed under either of\n\n* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n* Lesser General Public license v3.0 or later ([LICENSE-LGPL](LICENSE-LGPL) or https://www.gnu.org/licenses/lgpl-3.0.html)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the LGPL-3.0 license, shall be dual licensed as above, without any\nadditional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqedk%2Fini-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqedk%2Fini-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqedk%2Fini-rs/lists"}