Uclicious

Uclicious is a wrapper around Universal Configuration Library (UCL) parser with a lot of sugar.

Uclicious is built on top of libucl. It is much more complex than json or TOML, so I recommend reading documentaiton about it. Library provides safe, but raw API to that library: ```rust use uclicious::*; let mut parser = Parser::default(); let input = r#" teststring = "no scope" afloat = 3.14 aninteger = 69420 isitgood = yes buffersize = 1KB "#; parser.addchunkfull(input, Priority::default(), DEFAULTDUPLICATESTRATEGY).unwrap(); let result = parser.get_object().unwrap();

let lookupresult = result.lookup("teststring").unwrap().asstring().unwrap(); asserteq!(lookupresult.asstr(), "no scope");

let lookupresult = result.lookup("afloat").unwrap().asf64().unwrap(); asserteq!(lookup_result, 3.14f64);

let lookupresult = result.lookup("aninteger").unwrap().asi64().unwrap(); asserteq!(lookup_result, 69420i64);

let lookupresult = result.lookup("isitgood").unwrap().asbool().unwrap(); asserteq!(lookupresult, true);

let lookupresult = result.lookup("buffersize").unwrap().asi64().unwrap(); asserteq!(lookup_result, 1024); ```

In order to get around rust rules library implemets its own trait FromObject for some basic types: ```rust use uclicious::*; let mut parser = Parser::default(); let input = r#" teststring = "no scope" afloat = 3.14 aninteger = 69420 isitgood = yes buffersize = 1KB "#; parser.addchunkfull(input, Priority::default(), DEFAULTDUPLICATESTRATEGY).unwrap(); let result = parser.get_object().unwrap();

let lookupresult = result.lookup("isitgood").unwrap(); let maybe: Option = FromObject::tryfrom(lookupresult).unwrap(); asserteq!(Some(true), maybe); ```

Automatic Derive

On top of "raw" interface to libUCL, Uclicious provides an easy way to derive constructor for strucs: ```rust use uclicious::*; use std::path::PathBuf; use std::net::SocketAddr; use std::collections::HashMap;

[derive(Debug,Uclicious)]

[ucl(var(name = "test", value = "works"))]

struct Connection { #[ucl(default)] enabled: bool, host: String, #[ucl(default = "420")] port: i64, buffer: u64, #[ucl(path = "type")] kind: String, locations: Vec, addr: SocketAddr, extra: Extra, #[ucl(path = "subsection.host")] hosts: Vec, #[ucl(default)] option: Option, gates: HashMap, }

[derive(Debug,Uclicious)]

[ucl(skip_builder)]

struct Extra { enabled: bool } let mut builder = Connection::builder().unwrap();

let input = r#" enabled = yes host = "some.fake.url" buffer = 1mb type = $test locations = "/etc/" addr = "127.0.0.1:80" extra = { enabled = on } subsection { host = [host1, host2] } gates { feature1 = on feature2 = off feature_3 = on }"#;

builder.addchunkfull(input, Priority::default(), DEFAULTDUPLICATESTRATEGY).unwrap(); let connection: Connection = builder.build().unwrap(); ```

If you choose to derive builder then ::builder() method will be added to target struct.

Supported attributes (#[ucl(..)])

Structure level

• skip_builder
  • if set, then builder and builder methods won't be generated.
• parser(..)
  • Optional attribute to configure inner parser.
  • Has following nested attributes:
    • flags
      • a path to function that returns flags.
• var(..)
  • Optional attribute to register string variables with the parser.
  • Has following nested attributes:
    • name
      • A name of the variable without $ part.
    • value
      • A string values for the variable.
      • Onlt string variables are supported by libUCL.
• include(..)
  • Used to add files into the parser.
  • If file doesn't exist or failed to parse, then error will be returned in a constructor.
  • Has following nested attirbutes:
    • (required) path(string)
      • File path. Can be absolute or relative to CWD.
    • (optional) priority(u32)
      • 0-15 priority for the source. Consult the libUCL documentation for more information.
    • (optional) strategy(uclicious::DuplicateStrategy)
      • Strategy to use for duplicate keys. Consult the libUCL documentation for more information.

Field level

• default
  • Use Default::default if key not found in object.
• default(expression)
  • Use this expression as value if key not found.
  • Could be a value or a function call.
• path(string)
  • By default field name is used as path.
  • If set that would be used as a key.
  • dot notation for key is supported.

Additional notes

• If target type is an array, but key is a single value — an implicit list is created.
• Automatic derive on enums is not supported, but you can implement it yourself.
• I have a few more features I want to implement before publishing this crate:
  • Ability to add variables.
  • Ability to add macross handlers.
  • (maybe) configure parser that us used for derived builder with atrributes.
  • (done) add sources to parser with attributes.

Contributing

PRs, feature requests, bug reports are welcome. I won't be adding CoC — be civilized.

Goals

• Provider safe and convient configuration library
• Automatic derive, so you don't have to think about parser object

Not Goals

• Providing UCL Object generation tools is not a goal for this project
• 1:1 interface to libUCL
• sugar inside raw module

Special thanks

• draft6 and hauleth
  • libucl-rs was a good starting point
  • Type wrappers pretty much copied from there
• colin-kiegel
  • Rust-derive-builder was used as a starting point for uclicious-derive
  • Very well documented proc_macro crate, do recommend

LICENSE

BSD-2-Clause.