Crate ion_rs

Expand description

Reading and writing `Element`s

The Element API offers a convenient way to read and write Ion data when its exact shape is not known ahead of time.

Each Element represents an (annotations, value) pair. If the value is a container (an Ion list, sexp, or struct), then it will contain its own collection of Elements. Elements can be nested to arbitrary depth.

Constructing an `Element`

From text Ion

The Element::read_one method will parse the provided data and requires that it contain exactly one Ion value.

use ion_rs::element::Element;
use ion_rs::IonType;
let ion_data = "[1, 2, 3]";
let element = Element::read_one(ion_data)?;
assert_eq!(element.ion_type(), IonType::List);

Element::read_all will read any number of Ion values and return them as a Vec<Element>.

Element::read_first will read the first Ion value without requiring that the stream have exactly one value.

From a Rust value

Most Rust primitives implement Into<Element>, allowing them to be converted to an Ion Element directly.

use ion_rs::element::Element;

let int: Element = 5.into();
assert_eq!(Element::read_one("5")?, int);

let boolean: Element = true.into();
assert_eq!(Element::read_one("true")?, boolean);

let string: Element = "hello".into();
assert_eq!(Element::read_one("\"hello\"")?, string);

let ion_version_marker: &[u8] = &[0xE0, 0x01, 0x00, 0xEA]; // Ion 1.0 version marker
let blob: Element = ion_version_marker.into();
assert_eq!(Element::read_one("{{4AEA6g==}}")?, blob);

Using macros

When constructing a container Element, you can use the ion_list!, ion_sexp!, and ion_struct! macros.

use ion_rs::element::Element;
use ion_rs::{ion_list, ion_sexp, ion_struct};

// Variable names are allowed
let six = 6i64;
let list: Element = ion_list! [true, six, "foo"].into();
assert_eq!(Element::read_one("[true, 6, \"foo\"]")?, list);

// Nested use of macros is allowed
// Notice that ion_sexp! uses ()s without commas
let sexp: Element = ion_sexp! (true six ion_list!["foo", "bar"]).into();
assert_eq!(Element::read_one("(true 6 [\"foo\", \"bar\"])")?, sexp);

let field_name = "bar";
let struct_: Element = ion_struct! {
  "foo": six,
  field_name: false
}.into();
assert_eq!(Element::read_one("{foo: 6, bar: false}")?, struct_);

From a stream

use ion_rs::element::reader::ElementReader;
use ion_rs::element::Element;
use ion_rs::ReaderBuilder;
use std::fs::File;
let ion_file = File::open("/foo/bar/baz.ion").unwrap();
let mut reader = ReaderBuilder::default().build(ion_file)?;
// A simple pretty-printer
for element in reader.elements() {
    println!("{}", element?)
}

Traversing an `Element`

use ion_rs::IonResult;
use ion_rs::element::{Element, IntoAnnotatedElement, Value};
use ion_rs::{ion_list, ion_struct};
let element: Element = ion_struct! {
  "foo": "hello",
  "bar": true,
  "baz": ion_list! [4, 5, 6]
}
.into();

if let Value::Struct(s) = element.value() {
    if let Some(Value::List(l)) = s.get("baz").map(|b| b.value()) {
        for (index, element) in l.elements().enumerate() {
            println!("{}. {}", index + 1, element);
            // 1) 4
            // 2) 5
            // 3) 6
        }
    }
}

Writing an `Element` to an `io::Write`

use ion_rs::IonResult;
use ion_rs::element::writer::ElementWriter;
use ion_rs::element::{Element, IntoAnnotatedElement, Value};
use ion_rs::{ion_list, ion_struct, IonWriter, TextWriterBuilder};
let element: Element = ion_struct! {
  "foo": "hello",
  "bar": true,
  "baz": ion_list! [4, 5, 6]
}
.into();

let mut buffer: Vec<u8> = Vec::new();
let mut writer = TextWriterBuilder::default().build(&mut buffer)?;
writer.write_element(&element)?;
writer.flush()?;
assert_eq!(
    "{foo: \"hello\", bar: true, baz: [4, 5, 6]}".as_bytes(),
    writer.output().as_slice()
);

Re-exports

pub use types::Decimal;
pub use types::Int;
pub use types::IonType;
pub use types::Str;
pub use types::Symbol;
pub use types::Timestamp;
pub use binary::binary_writer::BinaryWriter;
pub use binary::binary_writer::BinaryWriterBuilder;
pub use binary::raw_binary_writer::RawBinaryWriter;
pub use raw_reader::RawReader;
pub use raw_reader::RawStreamItem;
pub use reader::Reader;
pub use reader::ReaderBuilder;
pub use reader::StreamItem;
pub use reader::UserReader;
pub use text::raw_text_writer::RawTextWriter;
pub use text::raw_text_writer::RawTextWriterBuilder;
pub use result::IonError;
pub use result::IonResult;

Modules

binary
This module provides the necessary structures and logic to read values from a binary Ion data stream.
constants
data_source
element
Provides a dynamically typed, materialized representation of an Ion value.
external
Re-exports of third party dependencies that are part of our public API.
raw_reader
reader
result
text
types
This module provides an implementation of the data types described by the Ion Data Model section of the Ion 1.0 spec.

Macros

ion_list
Constructs a list Element with the specified child values.
ion_sexp
Constructs an s-expression Element with the specified child values.
ion_struct
Constructs an struct Element with the specified fields.

Structs

BlockingRawReader
The BlockingRawReader wraps a non-blocking RawReader that implements the BufferedReader trait, providing a blocking RawReader.
IonData
A wrapper for lifting Ion compatible data into using Ion-oriented comparisons (versus the Rust value semantics). This enables the default semantics to be what a Rust user expects for native values, but allows a user to opt-in to Ion’s structural equivalence/order.
SymbolRef
A reference to a fully resolved symbol. Like Symbol (a fully resolved symbol with a static lifetime), a SymbolRef may have known or undefined text (i.e. $0).
SymbolTable
Stores mappings from Symbol IDs to text and vice-versa.
SystemReader
A streaming Ion reader that:
TextWriter
An application-level text Ion writer. This writer manages a symbol table and so can convert symbol IDs to their corresponding text. However, unlike the BinaryWriter, it is capable of writing text to the output stream without first adding it to the symbol table.
TextWriterBuilder

Enums

RawSymbolToken
A symbol token encountered in a text or binary Ion stream. RawSymbolTokens do not store import source information for the token encountered. Similarly, a RawSymbolToken cannot store both a symbol ID and text, which means that it is not suitable for representing a resolved symbol.
RawSymbolTokenRef
Like RawSymbolToken, but the Text variant holds a borrowed reference instead of a String.
SystemStreamItem
Raw stream elements that a SystemReader may encounter.

Traits

IonDataSource
Optimized read operations for parsing Ion.
IonReader
This trait captures the format-agnostic parser functionality needed to navigate within an Ion stream and read the values encountered into native Rust data types.
IonWriter
This trait captures the format-agnostic encoding functionality needed to write native Rust types to a stream as Ion values.