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;
}