From 6fa2057af6102fe35b2ae6ebd96aef7e3cf5da49 Mon Sep 17 00:00:00 2001
From: "Kevin R. Thornton" <krthornt@uci.edu>
Date: Wed, 12 May 2021 11:25:06 -0700
Subject: [PATCH] Add prelude.rs (#119)

Remove macro to use all public traits (See PR #110)

Closes #118
---
 examples/tree_traversals.rs |  2 +-
 src/_macros.rs              | 13 -------------
 src/lib.rs                  | 16 ++++++++++++++++
 src/prelude.rs              | 12 ++++++++++++
 4 files changed, 29 insertions(+), 14 deletions(-)
 create mode 100644 src/prelude.rs

diff --git a/examples/tree_traversals.rs b/examples/tree_traversals.rs
index 3bf53a3e7..82ef308ef 100644
--- a/examples/tree_traversals.rs
+++ b/examples/tree_traversals.rs
@@ -1,5 +1,5 @@
 use clap::{value_t_or_exit, App, Arg};
-use streaming_iterator::StreamingIterator; // Required for tree iteration
+use tskit::prelude::*;
 
 // "Manual" traversal from samples to root
 fn traverse_upwards(tree: &tskit::Tree) {
diff --git a/src/_macros.rs b/src/_macros.rs
index 5b20cc663..38c547720 100644
--- a/src/_macros.rs
+++ b/src/_macros.rs
@@ -1,18 +1,5 @@
 #![macro_use]
 
-/// Convenience macro issuing `use` for all public traits.
-#[macro_export]
-macro_rules! enable_tskit_traits {
-    () => {
-        use $crate::metadata::MetadataRoundtrip;
-        #[cfg(feature = "provenance")]
-        use $crate::provenance::Provenance;
-        use $crate::NodeListGenerator;
-        use $crate::TableAccess;
-        use $crate::TskitTypeAccess;
-    };
-}
-
 #[doc(hidden)]
 macro_rules! handle_tsk_return_value {
     ($code: expr) => {{
diff --git a/src/lib.rs b/src/lib.rs
index 010a4dfca..2b6e59064 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -24,6 +24,21 @@
 //!     * Tree lifetimes are tied to that of the parent tree sequence.
 //!     * Table objects ([`NodeTable`], etc..) are only represented by non-owning, immutable types.
 //!
+//! ## Prelude
+//!
+//! The [`prelude`] module contains definitions that are difficult/annoying to live without.
+//! In particuar, this module exports various traits that make it so that client code does
+//! not have to `use` them a la carte.
+//!
+//! We recomment that client code import all symbols from this module:
+//!
+//! ```
+//! use tskit::prelude::*;
+//! ```
+//!
+//! The various documentation examples manually `use` each trait both in order
+//! to illustrate which traits are needed and to serve as doc tests.
+//!
 //! # Optional features
 //!
 //! Some features are optional, and are activated by requesting them in your `Cargo.toml` file.
@@ -60,6 +75,7 @@ mod migration_table;
 mod mutation_table;
 mod node_table;
 mod population_table;
+pub mod prelude;
 mod site_table;
 mod table_collection;
 mod table_iterator;
diff --git a/src/prelude.rs b/src/prelude.rs
new file mode 100644
index 000000000..ce475e219
--- /dev/null
+++ b/src/prelude.rs
@@ -0,0 +1,12 @@
+//! Export commonly-use types and traits
+
+pub use crate::tsk_flags_t;
+pub use crate::tsk_id_t;
+pub use crate::tsk_size_t;
+pub use crate::NodeListGenerator;
+pub use crate::TableAccess;
+pub use crate::TskitTypeAccess;
+pub use crate::TSK_NODE_IS_SAMPLE;
+pub use crate::TSK_NULL;
+pub use streaming_iterator::DoubleEndedStreamingIterator;
+pub use streaming_iterator::StreamingIterator;