Struct AbxParser

Source

pub struct AbxParser<'a> { /* private fields */ }

Expand description

A pull parser over an ABX document in memory.

Call next_event until it returns None, or use a helper such as to_xml or find_attribute. Helpers consume events, so each call continues where the previous one stopped.

To read from a file or another Read source, use AbxStreamParser, which has the same methods.

§Examples

use android_abx::{AbxParser, Event};

let mut parser = AbxParser::new(data)?;
assert_eq!(parser.next_event()?, Some(Event::StartDocument));
assert!(matches!(parser.next_event()?, Some(Event::StartTag { name, .. }) if name == "pkg"));

Implementations§

Source §

impl<'a> AbxParser<'a>

Source

pub fn new(input: &'a [u8]) -> Result<Self>

Creates a parser over input and checks its header.

§Errors

Returns AbxError::UnexpectedEof if input is shorter than 4 bytes, or AbxError::InvalidMagic if it does not start with MAGIC.

Source

pub fn is_empty(&self) -> bool

Returns true if all the input has been read.

Source

pub fn next_event(&mut self) -> Result<Option<Event>>

Reads the next event, or returns None at the end of the input.

§Errors

Returns an error if the input is truncated or malformed (unknown token, invalid interned-string index, invalid UTF-8). On error, the parser is left at the start of the failing event.

Source

pub fn collect_events(&mut self) -> Result<Vec<Event>>

Reads all remaining events into a Vec.

§Errors

Returns an error if the input is truncated or malformed (unknown token, invalid interned-string index, invalid UTF-8).

Source

pub fn find_attribute( &mut self, element: &str, attr: &str, ) -> Result<Option<AttributeValue>>

Returns the value of attribute attr on the next <element> tag that has it.

Events are consumed up to and including the matching tag. Returns Ok(None) if the document ends first.

§Errors

Returns an error if the input is truncated or malformed (unknown token, invalid interned-string index, invalid UTF-8).

§Examples

use android_abx::{AbxParser, AttributeValue};

let mut parser = AbxParser::new(data)?;
let name = parser.find_attribute("pkg", "name")?;
assert_eq!(name, Some(AttributeValue::String("com.example.chat".into())));

Source

pub fn find_all_attributes( &mut self, element: &str, attr: &str, ) -> Result<Vec<AttributeValue>>

Returns the value of attribute attr on every remaining <element> tag.

Tags without attr are skipped. Consumes the rest of the document.

§Errors

Returns an error if the input is truncated or malformed (unknown token, invalid interned-string index, invalid UTF-8).

Source

pub fn attributes_of(&mut self, element: &str) -> Result<Option<Vec<Attribute>>>

Returns the attributes of the next <element> tag.

Events are consumed up to and including the matching tag. Returns Ok(None) if the document ends first.

§Errors

Returns an error if the input is truncated or malformed (unknown token, invalid interned-string index, invalid UTF-8).

Source

pub fn all_attributes_of( &mut self, element: &str, ) -> Result<Vec<Vec<Attribute>>>

Returns the attributes of every remaining <element> tag.

Consumes the rest of the document.

§Errors

Returns an error if the input is truncated or malformed (unknown token, invalid interned-string index, invalid UTF-8).

Source

pub fn to_xml(&mut self) -> Result<String>

Renders the remaining events as an XML string.

The output starts with an <?xml ...?> declaration. Text and attribute values are escaped; empty elements are written as an opening and a closing tag.

§Errors

Returns an error if the input is truncated or malformed (unknown token, invalid interned-string index, invalid UTF-8).

§Examples

use android_abx::AbxParser;

let xml = AbxParser::new(data)?.to_xml()?;
assert!(xml.ends_with(r#"<pkg name="com.example.chat" version="3" flags="1"></pkg>"#));

Source

pub fn write_xml(&mut self, writer: &mut impl Write) -> Result<()>

Writes the remaining events as XML to writer.

Same output as to_xml, without building the whole string in memory.

§Errors

Returns an error if the input is truncated or malformed (unknown token, invalid interned-string index, invalid UTF-8). Also returns AbxError::Io if reading or writing fails.

Source

pub fn deserialize_next<T: DeserializeOwned>( &mut self, element: &str, ) -> Result<Option<T>>

Available on crate feature serde only.

Deserializes the next <element> into T.

Events are consumed up to and including the element’s closing tag. Returns Ok(None) if the document ends first. See Deserializing with serde for how fields are matched.

§Errors

Returns a parse error if the input is malformed, or AbxError::Deserialization if the element does not match T.

§Examples

use android_abx::AbxParser;
use serde::Deserialize;

#[derive(Deserialize)]
struct Permission {
    name: String,
}

#[derive(Deserialize)]
struct Pkg {
    name: String,
    description: String,
    permission: Vec<Permission>,
}

let mut parser = AbxParser::new(data)?;
let pkg: Pkg = parser.deserialize_next("pkg")?.unwrap();
assert_eq!(pkg.name, "com.example.chat");
assert_eq!(pkg.description, "A chat app");
assert_eq!(pkg.permission.len(), 2);