Crate serde_java_properties[][src]

Expand description

Serde Java Properties

Java Properties is a simple, line-oriented format for specifying key-value resources used in Java programs. This crate offers basic (de-)serializers for use with serde-enabled datastructures.

field_a: a value
field_b: 100
field_c: true

Implementation

Internally, the java-properties crate is used for iterating key-value pairs in an input stream, and writing key-value pairs to an output stream.

Deserializing a struct

Usually, the format is untyped i.e. it deserialises to a map from String to String. This crate uses the default std::str::FromStr implementations for integers, floats and bool to provide a typed interface on top of that. That way, simple structures or maps that implement serde::Deserialize can be loaded from properties files.

#[derive(Debug, PartialEq, Deserialize)]
struct Data {
    field_a: String,
    field_b: usize,
    field_c: bool,
}
let text = "
field_a: a value
field_b: 100
field_c: true
";

let data: Data = serde_java_properties::from_str(text).unwrap();

assert_eq!(data.field_a, "a value");
assert_eq!(data.field_b, 100);
assert_eq!(data.field_c, true);

Serializing a struct

Serialization uses the default std::fmt::Display implementations for each primitive type.

Supported in the top-level Serializer:

  • Maps
  • Structs
  • Enums of struct variants
  • Options of all of these

Supported in the field-level Serializer:

  • Integers (i8, i16, i32, i64, u8, u16, u32, u64)
  • Floats (f32, f64)
  • Booleans (true or false)
  • Strings
  • Enums of unit variants
  • Options of all of these
#[derive(Debug, PartialEq, Serialize)]
struct Data {
    field_a: String,
    field_b: usize,
    field_c: bool,
}

let data = Data { field_a: "value".to_string(), field_b: 100, field_c: true };
let string = serde_java_properties::to_string(&data).unwrap();

assert_eq!(string, "field_a=value\nfield_b=100\nfield_c=true\n");

Tagged Enums

Internally tagged enums are generally supported.

Because of a limitation in serde, type hints are not available in this case, which means that the serde::Deserializer::deserialize_any method on the FieldDeserializer is called which only implements a limited heuristic as to which serde::de::Visitor method to call.

use serde::{Deserialize, Serialize};

#[derive(Debug, PartialEq, Deserialize, Serialize)]
#[serde(tag = "type")]
pub enum Test {
    Var1 { key: usize, },
    Var2 { msg: String, },
}

let test1 = Test::Var1 { key: 1000 };
let test2 = Test::Var2 { msg: "serde".to_string() };

let text1 = serde_java_properties::to_string(&test1).unwrap();
let text2 = serde_java_properties::to_string(&test2).unwrap();

assert_eq!(text1, "type=Var1\nkey=1000\n");
assert_eq!(text2, "type=Var2\nmsg=serde\n");

let re1: Test = serde_java_properties::from_str(&text1).unwrap();
let re2: Test = serde_java_properties::from_str(&text2).unwrap();

Unit Struct Variants

For simple enums, the name of the variant is used as the value

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
enum Switch { On, Off }
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
struct House { light: Switch, }

let text = "light: On";
let data: House = serde_java_properties::from_str(&text).unwrap();

assert_eq!(data.light, Switch::On);
let out = serde_java_properties::to_string(&data).unwrap();

assert_eq!(out, "light=On\n");

Alternatives

Similar to the java-properties crate itself, this crate is supposed to be an exact match to the format as specified in Java.

If you need a more powerful configuration syntax, that supports nested structs, you should probably use HOCON.

Re-exports

pub use de::Deserializer;
pub use ser::Serializer;

Modules

Deserialization

Serialization

Constants

UTF-8 Encoding from the encoding crate for use with the *_with_encoding functions.

Functions

Turn a reader into a value of T

Turn a reader into a value of T using the given encoding

Turn a byte slice into a value of T

Turn a byte slice into a value of T using the given encoding

Turn a string into a value of T

Write a properties file to a string

Write a properties file to a byte buffer

Write a properties file to a byte buffer with the specified encoding

Write a properties file to a io::Write implementation

Write a properties file to a io::Write implementation using the provided encoding