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 interval = 1s "#; 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!(lookupresult, 1024); let lookupresult = result.lookup("interval").unwrap().astime().unwrap(); asserteq!(lookup_result, 1.0f64); ```

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; use std::time::Duration;

[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, interval: Duration, }

[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] } interval = 10ms 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.

Validators

Library supports running optional validators on values before building the resulting struct:

```rust use uclicious::*; mod validators { use uclicious::ObjectError; pub fn ispositive(lookuppath: &str, value: &i64) -> Result<(), ObjectError> { if *value > 0 { Ok(()) } else { Err(ObjectError::other(format!("{} is not a positive number", lookup_path))) } } }

[derive(Debug,Uclicious)]

struct Validated { #[ucl(default, validate="validators::is_positive")] number: i64 } let mut builder = Validated::builder().unwrap();

let input = "number = -1"; builder.addchunkfull(input, Priority::default(), DEFAULTDUPLICATESTRATEGY).unwrap(); assert!(builder.build().is_err()) ```

Type Mapping

If your target structure has types that don't implement FromObject you can use From or TryFrom via intermediate that does:

```rust use uclicious::*; use std::convert::{From,TryFrom};

[derive(Debug, Eq, PartialEq)]

enum Mode { On, Off, }

impl TryFrom for Mode { type Error = ObjectError; fn tryfrom(src: String) -> Result { match src.tolowercase().as_str() { "on" => Ok(Mode::On), "off" => Ok(Mode::Off), _ => Err(ObjectError::other(format!("{} is not supported value", src))) } } }

[derive(Debug, Eq, PartialEq)]

struct WrappedInt(i64);

impl From for WrappedInt { fn from(src: i64) -> WrappedInt { WrappedInt(src) } }

[derive(Debug,Uclicious, Eq, PartialEq)]

struct Mapped { #[ucl(from="i64")] number: WrappedInt, #[ucl(try_from="String")] mode: Mode } let mut builder = Mapped::builder().unwrap();

let input = r#" number = -1, mode = "on" "#; builder.addchunkfull(input, Priority::default(), DEFAULTDUPLICATESTRATEGY).unwrap(); let actual = builder.build().unwrap(); let expected = Mapped { number: WrappedInt(-1), mode: Mode::On }; assert_eq!(expected, actual); ```

Additionally you can provide mapping to you type from ObjectRef: ```rust use uclicious::*;

[derive(Debug, Eq, PartialEq)]

pub enum Mode { On, Off, }

pub fn mapbool(src: ObjectRef) -> Result { let bool: bool = src.tryinto()?; if bool { Ok(Mode::On) } else { Ok(Mode::Off) } }

[derive(Debug,Uclicious, Eq, PartialEq)]

struct Mapped { #[ucl(map="map_bool")] mode: Mode } let mut builder = Mapped::builder().unwrap();

let input = r#" mode = on "#; builder.addchunkfull(input, Priority::default(), DEFAULTDUPLICATESTRATEGY).unwrap(); let actual = builder.build().unwrap(); let expected = Mapped { mode: Mode::On }; ```

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.
    • filevars(..)
      • call set_filevars on a parser.
      • Has following nested attributes:
        • path
          • a string representation of filepath.
        • expand
          • (optional) if set, then variables would be expanded to absolute.
• 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

All field level options are optional.

• 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.
• validate = path::to_method
  • Fn(key: &str, value: &T) -> Result<(), E>
  • Error needs to be convertable into ObjectError
• from = Type
  • Try to convert ObjectRef to Type and then use std::convert::From to convert into target type
• try_from = Type
  • Try to convert ObjectRef to Type and then use std::convert::TryFrom to convert into target type
  • Error will be converted into ObjectError::Other
• map = path::to_method
  • Fn(src: ObjectRef) -> Result<T, E>
  • A way to map foreign objects that can't implement From or TryFrom or when error is not convertable into ObjectError

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.

Particular Contributions of Interest

• Optimize derive code.
• Improve documentation — I often write late and night and some it might look like a word soup.
• Better tests
• from and try_from like in serder [#3]
• Glob support in derive parser section

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.