Crate candid_parser

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

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