Struct prost_build::Config

pub struct Config { /* private fields */ }

Configuration options for Protobuf code generation.

This configuration builder can be used to set non-default code generation options.

Implementations

impl Config

pub fn new() -> Config

Creates a new code generator configuration with default options.

pub fn btree_map<I, S>(&mut self, paths: I) -> &mut Selfwhere
    I: IntoIterator<Item = S>,
    S: AsRef<str>,

Configure the code generator to generate Rust BTreeMap fields for Protobuf map type fields.

Arguments

paths - paths to specific fields, messages, or packages which should use a Rust BTreeMap for Protobuf map fields. Paths are specified in terms of the Protobuf type name (not the generated Rust type name). Paths with a leading . are treated as fully qualified names. Paths without a leading . are treated as relative, and are suffix matched on the fully qualified field name. If a Protobuf map field matches any of the paths, a Rust BTreeMap field is generated instead of the default HashMap.

The matching is done on the Protobuf names, before converting to Rust-friendly casing standards.

Examples

// Match a specific field in a message type.
config.btree_map(&[".my_messages.MyMessageType.my_map_field"]);

// Match all map fields in a message type.
config.btree_map(&[".my_messages.MyMessageType"]);

// Match all map fields in a package.
config.btree_map(&[".my_messages"]);

// Match all map fields.
config.btree_map(&["."]);

// Match all map fields in a nested message.
config.btree_map(&[".my_messages.MyMessageType.MyNestedMessageType"]);

// Match all fields named 'my_map_field'.
config.btree_map(&["my_map_field"]);

// Match all fields named 'my_map_field' in messages named 'MyMessageType', regardless of
// package or nesting.
config.btree_map(&["MyMessageType.my_map_field"]);

// Match all fields named 'my_map_field', and all fields in the 'foo.bar' package.
config.btree_map(&["my_map_field", ".foo.bar"]);

pub fn field_attribute<P, A>(&mut self, path: P, attribute: A) -> &mut Selfwhere
    P: AsRef<str>,
    A: AsRef<str>,

Add additional attribute to matched fields.

Arguments

path - a patch matching any number of fields. These fields get the attribute. For details about matching fields see btree_map.

attribute - an arbitrary string that’ll be placed before each matched field. The expected usage are additional attributes, usually in concert with whole-type attributes set with type_attribute, but it is not checked and anything can be put there.

Note that the calls to this method are cumulative ‒ if multiple paths from multiple calls match the same field, the field gets all the corresponding attributes.

Examples

// Prost renames fields named `in` to `in_`. But if serialized through serde,
// they should as `in`.
config.field_attribute("in", "#[serde(rename = \"in\")]");

pub fn type_attribute<P, A>(&mut self, path: P, attribute: A) -> &mut Selfwhere
    P: AsRef<str>,
    A: AsRef<str>,

Add additional attribute to matched messages, enums and one-ofs.

Arguments

paths - a path matching any number of types. It works the same way as in btree_map, just with the field name omitted.

attribute - an arbitrary string to be placed before each matched type. The expected usage are additional attributes, but anything is allowed.

The calls to this method are cumulative. They don’t overwrite previous calls and if a type is matched by multiple calls of the method, all relevant attributes are added to it.

For things like serde it might be needed to combine with field attributes.

Examples

// Nothing around uses floats, so we can derive real `Eq` in addition to `PartialEq`.
config.type_attribute(".", "#[derive(Eq)]");
// Some messages want to be serializable with serde as well.
config.type_attribute("my_messages.MyMessageType",
                      "#[derive(Serialize)] #[serde(rename-all = \"snake_case\")]");
config.type_attribute("my_messages.MyMessageType.MyNestedMessageType",
                      "#[derive(Serialize)] #[serde(rename-all = \"snake_case\")]");

Oneof fields

The oneof fields don’t have a type name of their own inside Protobuf. Therefore, the field name can be used both with type_attribute and field_attribute ‒ the first is placed before the enum type definition, the other before the field inside corresponding message struct.

In other words, to place an attribute on the enum implementing the oneof, the match would look like my_messages.MyMessageType.oneofname.

pub fn service_generator(
    &mut self,
    service_generator: Box<dyn ServiceGenerator>
) -> &mut Self

Configures the code generator to use the provided service generator.

pub fn compile_well_known_types(&mut self) -> &mut Self

Configures the code generator to not use the prost_types crate for Protobuf well-known types, and instead generate Protobuf well-known types from their .proto definitions.

pub fn retain_enum_prefix(&mut self) -> &mut Self

Configures the code generator to not strip the enum name from variant names.

Protobuf enum definitions commonly include the enum name as a prefix of every variant name. This style is non-idiomatic in Rust, so by default prost strips the enum name prefix from variants which include it. Configuring this option prevents prost from stripping the prefix.

pub fn compile_protos<P>(&mut self, protos: &[P], includes: &[P]) -> Result<()>where
    P: AsRef<Path>,

Compile .proto files into Rust files during a Cargo build with additional code generator configuration options.

This method is like the prost_build::compile_protos function, with the added ability to specify non-default code generation options. See that function for more information about the arguments and generated outputs.

Example build.rs

extern crate prost_build;

fn main() {
    let mut prost_build = prost_build::Config::new();
    prost_build.btree_map(&["."]);
    prost_build.compile_protos(&["src/frontend.proto", "src/backend.proto"],
                               &["src"]).unwrap();
}

Trait Implementations

impl Default for Config

fn default() -> Config

Returns the “default value” for a type.