Crate candid_parser

Expand description

§Candid Parser

Everything from candid crate is re-exported here. Users don’t have to add candid as their dependency in Cargo.toml.

Provides parser for Candid type and value.

str.parse::<IDLProg>() parses the Candid signature file to Candid AST.
parse_idl_args() parses the Candid value in text format to a struct IDLArg that can be used for serialization and deserialization between Candid and an enum type IDLValue in Rust.

§Parse `candid::IDLArgs`

We provide a parser to parse Candid values in text format.

use candid::{IDLArgs, TypeEnv};
use candid_parser::parse_idl_args;
// Candid values represented in text format
let text_value = r#"
     (42, opt true, vec {1;2;3},
      opt record {label="text"; 42="haha"})
"#;

// Parse text format into IDLArgs for serialization
let args: IDLArgs = parse_idl_args(text_value)?;
let encoded: Vec<u8> = args.to_bytes()?;

// Deserialize into IDLArgs
let decoded: IDLArgs = IDLArgs::from_bytes(&encoded)?;
assert_eq!(encoded, decoded.to_bytes()?);

// Convert IDLArgs to text format
let output: String = decoded.to_string();
let parsed_args: IDLArgs = parse_idl_args(&output)?;
let annotated_args = args.annotate_types(true, &TypeEnv::new(), &parsed_args.get_types())?;
assert_eq!(annotated_args, parsed_args);

Note that when parsing Candid values, we assume the number literals are always of type Int. This can be changed by providing the type of the method arguments, which can usually be obtained by parsing a Candid file in the following section.

§Operating on Candid AST

We provide a parser and type checker for Candid files specifying the service interface.

use candid::{TypeEnv, types::{Type, TypeInner}};
use candid_parser::{IDLProg, check_prog};
let did_file = r#"
    type List = opt record { head: int; tail: List };
    type byte = nat8;
    service : {
      f : (byte, int, nat, int8) -> (List);
      g : (List) -> (int) query;
    }
"#;

// Parse did file into an AST
let ast: IDLProg = did_file.parse()?;

// Type checking a given .did file
// let (env, opt_actor) = check_file("a.did")?;
// Or alternatively, use check_prog to check in-memory did file
// Note that file import is ignored by check_prog.
let mut env = TypeEnv::new();
let actor: Type = check_prog(&mut env, &ast)?.unwrap();

let method = env.get_method(&actor, "g").unwrap();
assert_eq!(method.is_query(), true);
assert_eq!(method.args, vec![TypeInner::Var("List".to_string()).into()]);

§Serializing untyped Candid values with type annotations.

With type signatures from the Candid file, candid::IDLArgs uses to_bytes_with_types function to serialize arguments directed by the Candid types. This is useful when serializing different number types and recursive types. There is no need to use types for deserialization as the types are available in the Candid message.

use candid::{IDLArgs, types::value::IDLValue};
use candid_parser::parse_idl_args;
// Get method type f : (byte, int, nat, int8) -> (List)
let method = env.get_method(&actor, "f").unwrap();
let args = parse_idl_args("(42, 42, 42, 42)")?;
// Serialize arguments with candid types
let encoded = args.to_bytes_with_types(&env, &method.args)?;
let decoded = IDLArgs::from_bytes(&encoded)?;
assert_eq!(decoded.args,
       vec![IDLValue::Nat8(42),
            IDLValue::Int(42.into()),
            IDLValue::Nat(42u8.into()),
            IDLValue::Int8(42)
           ]);

Re-exports§

pub use error::pretty_parse;
pub use error::pretty_wrap;
pub use error::Error;
pub use error::Result;
pub use types::IDLProg;
pub use typing::check_file;
pub use typing::check_prog;
pub use typing::pretty_check_file;
pub use candid;

Modules§

arc: This module provides functions to serialize and deserialize types under std::sync::Arc shared reference type.
assistassist
binary_parser
bindings: Candid bindings for different languages.
configsconfigs
de: Deserialize Candid binary format to Rust data structures
error: When serializing or deserializing Candid goes wrong.
grammar
pretty: pretty printer for Candid type and value
randomrandom
rc: This module provides functions to serialize and deserialize types under std::rc::Rc shared reference type.
ser: Serialize a Rust data structure to Candid binary format
test
token
types
typing
utils

Macros§

Decode: Decode Candid message into a tuple of Rust values of the given types. Produces Err if the message fails to decode at any given types. If the message contains only one value, it returns the value directly instead of a tuple.
Encode: Encode sequence of Rust values into Candid message of type candid::Result<Vec<u8>>.
define_function: Define a function reference type.
define_service: Define a service reference type.
export_service
field: Construct a field type, which can be used in TypeInner::Record and TypeInner::Variant.
func: Construct a function type.
record: Construct a record type, e.g., record!{ label: Nat::ty(); 42: String::ty() }.
service: Construct a service type.
variant: Construct a variant type, e.g., variant!{ tag: <()>::ty() }.

Structs§

DecoderConfig: Config the deserialization quota, used to prevent spending too much time in decoding malicious payload.
Func
IDLArgs
Int
Nat
Principal: Generic ID on Internet Computer.
Reserved
Service
TypeEnv

Enums§

Empty
IDLValue
MotokoResult

Traits§

CandidType
Deserialize: A data structure that can be deserialized from any data format supported by Serde.

Functions§

decode_args: Decode a series of arguments, represented as a tuple. There is a maximum of 16 arguments supported.
decode_args_with_config
decode_one: Decode a single argument.
decode_one_with_config
encode_args: Serialize an encoding of a tuple to a vector of bytes.
encode_one: Serialize a single value to a vector of bytes.
parse_idl_args
parse_idl_value
write_args: Serialize an encoding of a tuple and write it to a Write buffer.

Attribute Macros§

candid_method

Derive Macros§

CandidType
Deserialize

Crate candid_parserCopy item path