protobuf/
lib.rs

1//! # Library to read and write protocol buffers data
2//!
3//! # Version 2 is stable
4//!
5//! Currently developed branch of rust-protobuf [is 3](https://docs.rs/protobuf/%3E=3.0.0-alpha).
6//! It has the same spirit as version 2, but contains numerous improvements like:
7//! * runtime reflection for mutability, not just for access
8//! * protobuf text format and JSON parsing (which rely on reflection)
9//! * dynamic message support: work with protobuf data without generating code from schema
10//!
11//! Stable version of rust-protobuf will be supported until version 3 released.
12//!
13//! [Tracking issue for version 3](https://github.com/stepancheg/rust-protobuf/issues/518).
14//!
15//! # How to generate rust code
16//!
17//! There are several ways to generate rust code from `.proto` files
18//!
19//! ## Invoke `protoc` programmatically with protoc-rust crate (recommended)
20//!
21//! Have a look at readme in [protoc-rust crate](https://docs.rs/protoc-rust/=2).
22//!
23//! ## Use pure rust protobuf parser and code generator
24//!
25//! Readme should be in
26//! [protobuf-codegen-pure crate](https://docs.rs/protobuf-codegen-pure/=2).
27//!
28//! ## Use protoc-gen-rust plugin
29//!
30//! Readme is [here](https://docs.rs/protobuf-codegen/=2).
31//!
32//! ## Generated code
33//!
34//! Have a look at generated files (for current development version),
35//! used internally in rust-protobuf:
36//!
37//! * [descriptor.rs](https://github.com/stepancheg/rust-protobuf/blob/master/protobuf/src/descriptor.rs)
38//!   for [descriptor.proto](https://github.com/stepancheg/rust-protobuf/blob/master/protoc-bin-vendored/include/google/protobuf/descriptor.proto)
39//!   (that is part of Google protobuf)
40//!
41//! # Copy on write
42//!
43//! Rust-protobuf can be used with [bytes crate](https://github.com/tokio-rs/bytes).
44//!
45//! To enable `Bytes` you need to:
46//!
47//! 1. Enable `with-bytes` feature in rust-protobuf:
48//!
49//! ```
50//! [dependencies]
51//! protobuf = { version = "~2.0", features = ["with-bytes"] }
52//! ```
53//!
54//! 2. Enable bytes option
55//!
56//! with `Customize` when codegen is invoked programmatically:
57//!
58//! ```ignore
59//! protoc_rust::run(protoc_rust::Args {
60//!     ...
61//!     customize: Customize {
62//!         carllerche_bytes_for_bytes: Some(true),
63//!         carllerche_bytes_for_string: Some(true),
64//!         ..Default::default()
65//!     },
66//! });
67//! ```
68//!
69//! or in `.proto` file:
70//!
71//! ```ignore
72//! import "rustproto.proto";
73//!
74//! option (rustproto.carllerche_bytes_for_bytes_all) = true;
75//! option (rustproto.carllerche_bytes_for_string_all) = true;
76//! ```
77//!
78//! With these options enabled, fields of type `bytes` or `string` are
79//! generated as `Bytes` or `Chars` respectively. When `CodedInputStream` is constructed
80//! from `Bytes` object, fields of these types get subslices of original `Bytes` object,
81//! instead of being allocated on heap.
82//!
83//! # Accompanying crates
84//!
85//! * [`protoc-rust`](https://docs.rs/protoc-rust/=2)
86//!   and [`protobuf-codegen-pure`](https://docs.rs/protobuf-codegen-pure/=2)
87//!   can be used to rust code from `.proto` crates.
88//! * [`protobuf-codegen`](https://docs.rs/protobuf-codegen/=2) for `protoc-gen-rust` protoc plugin.
89//! * [`protoc`](https://docs.rs/protoc/=2) crate can be used to invoke `protoc` programmatically.
90//! * [`protoc-bin-vendored`](https://docs.rs/protoc-bin-vendored/=2) contains `protoc` command
91//!   packed into the crate.
92
93#![deny(missing_docs)]
94#![deny(rustdoc::broken_intra_doc_links)]
95
96#[cfg(feature = "bytes")]
97extern crate bytes;
98#[cfg(feature = "with-serde")]
99extern crate serde;
100#[macro_use]
101#[cfg(feature = "with-serde")]
102extern crate serde_derive;
103pub use crate::cached_size::CachedSize;
104#[cfg(feature = "bytes")]
105pub use crate::chars::Chars;
106pub use crate::clear::Clear;
107pub use crate::coded_input_stream::CodedInputStream;
108pub use crate::coded_output_stream::CodedOutputStream;
109pub use crate::enums::ProtobufEnum;
110pub use crate::error::ProtobufError;
111pub use crate::error::ProtobufResult;
112#[allow(deprecated)]
113pub use crate::message::parse_from_bytes;
114#[cfg(feature = "bytes")]
115#[allow(deprecated)]
116pub use crate::message::parse_from_carllerche_bytes;
117#[allow(deprecated)]
118pub use crate::message::parse_from_reader;
119#[allow(deprecated)]
120pub use crate::message::parse_length_delimited_from;
121#[allow(deprecated)]
122pub use crate::message::parse_length_delimited_from_bytes;
123#[allow(deprecated)]
124pub use crate::message::parse_length_delimited_from_reader;
125pub use crate::message::Message;
126pub use crate::repeated::RepeatedField;
127pub use crate::singular::SingularField;
128pub use crate::singular::SingularPtrField;
129pub use crate::unknown::UnknownFields;
130pub use crate::unknown::UnknownFieldsIter;
131pub use crate::unknown::UnknownValue;
132pub use crate::unknown::UnknownValueRef;
133pub use crate::unknown::UnknownValues;
134pub use crate::unknown::UnknownValuesIter;
135
136// generated
137pub mod descriptor;
138pub mod plugin;
139pub mod rustproto;
140
141pub mod wire_format;
142
143mod clear;
144mod coded_input_stream;
145mod coded_output_stream;
146pub mod compiler_plugin;
147mod enums;
148pub mod error;
149pub mod ext;
150pub mod json;
151pub mod lazy;
152mod lazy_v2;
153mod message;
154pub mod reflect;
155mod repeated;
156pub mod rt;
157mod singular;
158pub mod text_format;
159pub mod types;
160pub mod well_known_types;
161mod well_known_types_util;
162
163// used by test
164#[cfg(test)]
165#[path = "../../protobuf-test-common/src/hex.rs"]
166mod hex;
167
168// used by rust-grpc
169pub mod descriptorx;
170
171mod cached_size;
172mod chars;
173#[doc(hidden)] // used by codegen
174pub mod rust;
175mod strx;
176mod unknown;
177mod varint;
178mod zigzag;
179
180mod misc;
181
182mod buf_read_iter;
183mod buf_read_or_reader;
184
185/// This symbol is in generated `version.rs`, include here for IDE
186#[cfg(never)]
187pub const VERSION: &str = "";
188/// This symbol is in generated `version.rs`, include here for IDE
189#[cfg(never)]
190#[doc(hidden)]
191pub const VERSION_IDENT: &str = "";
192include!(concat!(env!("OUT_DIR"), "/version.rs"));
protobuf/lib.rs

protobuf/
lib.rs
