1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
//! Additional, more convenient, functionality, which leverages the Rust //! standard library, layered on top of [`kul_core`]. //! //! This crate: //! //! * Provides [`Parser`]s, for [ready-made](common/index.html) use for common //! basic parsing applications, that set pre-chosen types for most of the //! generic parameters. //! //! * Re-exports all of [`kul_core`]. //! //! * Provides [`Datum`] reference types that wrap the standard [`Box`], [`Rc`], //! and [`Arc`] types, for heap-allocating `Datum`s. //! //! * Provides [`Text`] types that use heap allocation for their chunking. //! //! * Provides [`SourceStream`] types suitable for efficient use with streaming //! sources that buffer into heap-allocated string chunks. It is possible to //! achieve minimal copying such that streamed data is only copied once from the //! OS into the user-space string chunks. Once buffered, these types produce //! `Text` types that have zero-copy operation. //! //! * Avoids stack overflows (when possible) when dropping the provided //! heap-allocated `Datum` types, so they can handle being used for very-deep //! trees (e.g. long lists), by using a custom [`Drop`] implementation for them. //! (Otherwise the compiler's default drop recursion could overflow.) //! //! Unlike [`kul_core`], this crate's purpose mostly is to provide premade //! implementations intended for ready use. So, instead of placing such items //! in sub-modules named `premade`, they are placed at the top of their //! respective modules, including for the premade items re-exported from //! `kul_core`. //! //! [`kul_core`]: http://docs.rs/kul_core/latest/kul_core/ //! [`Parser`]: http://docs.rs/kul_core/latest/kul_core/struct.Parser.html //! [`Datum`]: http://docs.rs/kul_core/latest/kul_core/enum.Datum.html //! [`Box`]: http://doc.rust-lang.org/std/boxed/struct.Box.html //! [`Rc`]: http://doc.rust-lang.org/std/rc/struct.Rc.html //! [`Arc`]: http://doc.rust-lang.org/std/sync/struct.Arc.html //! [`Text`]: http://docs.rs/kul_core/latest/kul_core/trait.Text.html //! [`SourceStream`]: http://docs.rs/kul_core/latest/kul_core/trait.SourceStream.html //! [`Drop`]: http://doc.rust-lang.org/std/ops/trait.Drop.html #![forbid(unsafe_code)] // Warn about desired lints that would otherwise be allowed by default. #![warn( // Groups future_incompatible, nonstandard_style, rust_2018_compatibility, // unsure if needed with Cargo.toml having edition="2018" rust_2018_idioms, unused, clippy::all, clippy::pedantic, // Individual lints not included in above groups and desired. macro_use_extern_crate, missing_copy_implementations, missing_debug_implementations, missing_docs, // missing_doc_code_examples, // maybe someday private_doc_tests, // single_use_lifetimes, // annoying hits on invisible derived impls trivial_casts, trivial_numeric_casts, unreachable_pub, unused_import_braces, unused_lifetimes, unused_qualifications, unused_results, variant_size_differences, )] // Exclude (re-allow) undesired lints included in above groups. #![allow( explicit_outlives_requirements, // annoying hits on invisible derived impls clippy::non_ascii_literal, )] // Re-export everything from the core crate. (Except items shadowed by ours, // which are re-exported elsewhere.) #[doc(no_inline)] pub use kul_core::*; pub mod drop; /// `Parser`s and related types and functions, provided for convenience, that /// use recommended types for instantiating many of the generic parameters of /// this crate, for common basic parsing applications. pub mod common { mod helper; pub mod inmem; pub mod stream; } /// `SourceStream` types that use the `std` library, including heap allocation. pub mod source_stream { mod char_iter_src_strm; pub use char_iter_src_strm::*; mod strish_iter_src_strm; pub use strish_iter_src_strm::*; } // The below modules shadow those of `kul_core` but re-export everything from // those in addition to providing some of their own items. pub mod datum; /// Types for `Parser`s that use the `std` library, including heap allocation. /// Also re-exports the core crate's module and premades. pub mod parser { #[doc(no_inline)] pub use kul_core::parser::{*, premade::*}; mod box_alloc; pub use box_alloc::BoxDatumAllocator; mod rc_alloc; pub use rc_alloc::RcDatumAllocator; mod arc_alloc; pub use arc_alloc::ArcDatumAllocator; mod hashmap_bindings; pub use hashmap_bindings::HashMapOperatorBindings; } /// `Text` types that use the `std` library, including heap allocation. Also /// re-exports the core crate's module and premades. pub mod text { #[doc(no_inline)] pub use kul_core::text::{*, premade::*}; /// `TextChunk` types that use the `std` library, including heap allocation. /// Also re-exports the core crate's module and premades. pub mod chunk { #[doc(no_inline)] pub use kul_core::text::chunk::{*, premade::*}; mod pos_strish; pub use pos_strish::*; } mod vec; pub use vec::TextVec; }