Move our types around, add a prelude module.

This might move around a little bit more, but I want to just be able to
write `diesel::update`, the `use` statements for those functions are
really common and quite noisy. This means that we need to stop
recommending glob importing the top level, and give something to be glob
imported.

I *think* I want to re-export the prelude from the top level, but I'm
not 100% certain. An alternative would be to export some of our structs
from the prelude as well.

Fixes #93

CHANGELOG.md

@@ -3,6 +3,16 @@ All user visible changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/), as described
 for Rust libraries in [RFC #1105](https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md)
 
+## Unreleased
+
+### Changed
+
+* Moved most of our top level trait exports into a prelude module, and
+  re-exported our CRUD functions from the top level.
+  `diesel::query_builder::update` and friends are now `diesel::update`, and you
+  will get them by default if you import `diesel::*`. For a less aggressive
+  glob, you can import `diesel::prelude::*`, which will only export our traits.
+
 ## [0.4.1] 2016-01-11
 
 ### Changed

README.md

@@ -21,8 +21,8 @@ Once you've done that, you can already start using the query builder, and
 pulling out primitives.
 
 Much of the behavior in diesel comes from traits, and it is recommended that you
-import `diesel::*`. We avoid exporting generic type names, or any bare functions
-at that level.
+import `diesel::prelude::*`. We avoid exporting generic type names, or any bare
+functions at that level.
 
 ```rust
 #[macro_use]
@@ -219,10 +219,9 @@ later pass to the [`Connection`][connection]. Here's a simple example.
 
 ```rust
 fn change_users_name(connection: &Connection, target: i32, new_name: &str) -> QueryResult<User> {
-    use diesel::query_builder::update;
     use users::dsl::*;
 
-    update(users.filter(id.eq(target))).set(name.eq(new_name))
+    diesel::update(users.filter(id.eq(target))).set(name.eq(new_name))
         .get_result(&connection)
 }
 ```
@@ -278,10 +277,9 @@ support returning a record.
 
 ```rust
 fn delete_user(connection: &Connection, user: User) -> QueryResult<()> {
-    use diesel::query_builder::delete;
     use users::dsl::*;
 
-    let deleted_rows = try!(delete(users.filter(id.eq(user.id))).execute(&connection));
+    let deleted_rows = try!(diesel::delete(users.filter(id.eq(user.id))).execute(&connection));
     debug_assert!(deleted_rows == 1);
     Ok(())
 }

diesel/src/connection/cursor.rs

@@ -1,4 +1,4 @@
-use Queriable;
+use query_source::Queriable;
 use db_result::DbResult;
 use types::{NativeSqlType, FromSqlRow};
 

diesel/src/doctest_setup.rs

@@ -1,21 +1,21 @@
 extern crate dotenv;
 
-use diesel::*;
+use diesel::prelude::*;
 use self::dotenv::dotenv;
 
-fn connection_no_data() -> Connection {
+fn connection_no_data() -> diesel::Connection {
     dotenv().ok();
 
     let connection_url = ::std::env::var("DATABASE_URL").ok()
         .expect("DATABASE_URL must be set in order to run tests");
-    let connection = Connection::establish(&connection_url).unwrap();
+    let connection = diesel::Connection::establish(&connection_url).unwrap();
     connection.begin_test_transaction().unwrap();
     connection.execute("DROP TABLE IF EXISTS users").unwrap();
 
     connection
 }
 
-fn establish_connection() -> Connection {
+fn establish_connection() -> diesel::Connection {
     let connection = connection_no_data();
 
     connection.execute("CREATE TABLE users (

diesel/src/lib.rs

@@ -60,14 +60,21 @@ pub mod helper_types {
     pub type With<'a, Source, Other> = <Source as WithDsl<'a, Other>>::Output;
 }
 
+pub mod prelude {
+    //! Re-exports important traits and types. Meant to be glob imported when using Diesel.
+    pub use expression::{Expression, SelectableExpression, BoxableExpression};
+    pub use expression::expression_methods::*;
+    #[doc(inline)]
+    pub use persistable::Insertable;
+    pub use query_dsl::*;
+    pub use query_source::{QuerySource, Queriable, Table, Column, JoinTo};
+    pub use result::{QueryResult, TransactionError, TransactionResult, ConnectionError, ConnectionResult, OptionalExtension};
+}
+
 pub use connection::{Connection, Cursor};
-pub use expression::{Expression, SelectableExpression, BoxableExpression};
-pub use expression::expression_methods::*;
-pub use query_dsl::*;
-pub use query_source::{QuerySource, Queriable, Table, Column, JoinTo};
+pub use prelude::*;
 #[doc(inline)]
-pub use persistable::Insertable;
-pub use result::{QueryResult, TransactionError, TransactionResult, ConnectionError, ConnectionResult, OptionalExtension};
+pub use query_builder::functions::{insert, update, delete};
 pub use result::Error::NotFound;
 #[doc(inline)]
 pub use types::structs::data_types;

diesel/src/migrations/mod.rs

@@ -186,12 +186,10 @@ fn run_migrations<T>(conn: &Connection, migrations: T)
 fn run_migration(conn: &Connection, migration: Box<Migration>)
     -> Result<(), RunMigrationsError>
 {
-    use ::query_builder::insert;
-
     conn.transaction(|| {
         println!("Running migration {}", migration.version());
         try!(migration.run(conn));
-        try!(insert(&NewMigration(migration.version()))
+        try!(::insert(&NewMigration(migration.version()))
              .into(__diesel_schema_migrations)
              .execute(&conn));
         Ok(())
@@ -201,13 +199,11 @@ fn run_migration(conn: &Connection, migration: Box<Migration>)
 fn revert_migration(conn: &Connection, migration: Box<Migration>)
     -> Result<(), RunMigrationsError>
 {
-    use ::query_builder::delete;
-
     try!(conn.transaction(|| {
         println!("Rolling back migration {}", migration.version());
         try!(migration.revert(conn));
         let target = __diesel_schema_migrations.filter(version.eq(migration.version()));
-        try!(delete(target).execute(&conn));
+        try!(::delete(target).execute(&conn));
         Ok(())
     }));
     Ok(())

diesel/src/query_builder/functions.rs

@@ -25,9 +25,8 @@ use super::IncompleteInsertStatement;
 /// #
 /// # fn main() {
 /// #     use self::users::dsl::*;
-/// #     use diesel::query_builder::update;
 /// #     let connection = establish_connection();
-/// let command = update(users.filter(id.eq(1)))
+/// let command = diesel::update(users.filter(id.eq(1)))
 ///     .set(name.eq("James"));
 /// let updated_row = connection.query_one(command);
 /// // When passed to `query_one`, the update statement will gain `RETURNING *`
@@ -63,11 +62,10 @@ pub fn update<T: UpdateTarget>(source: T) -> IncompleteUpdateStatement<T> {
 /// #
 /// # fn delete() -> QueryResult<()> {
 /// #     use self::users::dsl::*;
-/// #     use diesel::query_builder::delete;
 /// #     let connection = establish_connection();
 /// #     let get_count = || users.count().first::<i64>(&connection).unwrap();
 /// let old_count = get_count();
-/// try!(delete(users.filter(id.eq(1))).execute(&connection));
+/// try!(diesel::delete(users.filter(id.eq(1))).execute(&connection));
 /// assert_eq!(old_count - 1, get_count());
 /// # Ok(())
 /// # }
@@ -92,10 +90,9 @@ pub fn update<T: UpdateTarget>(source: T) -> IncompleteUpdateStatement<T> {
 /// #
 /// # fn delete() -> QueryResult<()> {
 /// #     use self::users::dsl::*;
-/// #     use diesel::query_builder::delete;
 /// #     let connection = establish_connection();
 /// #     let get_count = || users.count().first::<i64>(&connection).unwrap();
-/// try!(delete(users).execute(&connection));
+/// try!(diesel::delete(users).execute(&connection));
 /// assert_eq!(0, get_count());
 /// # Ok(())
 /// # }

diesel/src/query_builder/mod.rs

@@ -4,7 +4,8 @@ pub mod pg;
 pub mod debug;
 
 mod delete_statement;
-mod functions;
+#[doc(hidden)]
+pub mod functions;
 mod limit_clause;
 mod offset_clause;
 mod order_clause;
@@ -13,7 +14,6 @@ mod where_clause;
 pub mod insert_statement;
 pub mod update_statement;
 
-pub use self::functions::*;
 #[doc(hidden)]
 pub use self::select_statement::SelectStatement;
 #[doc(inline)]

diesel/src/query_builder/select_statement/dsl_impls.rs

@@ -1,6 +1,6 @@
 use expression::*;
 use expression::aliased::Aliased;
-use query_builder::*;
+use query_builder::{Query, SelectStatement};
 use query_builder::limit_clause::*;
 use query_builder::offset_clause::*;
 use query_builder::order_clause::*;

diesel/src/query_source/joins.rs

@@ -1,4 +1,4 @@
-use {QuerySource, Table};
+use super::{QuerySource, Table};
 use query_builder::*;
 use expression::SelectableExpression;
 use types::Nullable;

diesel/src/types/impls/array.rs

@@ -4,7 +4,7 @@ use self::byteorder::{ReadBytesExt, WriteBytesExt, BigEndian};
 use std::error::Error;
 use std::io::Write;
 
-use Queriable;
+use query_source::Queriable;
 use super::option::UnexpectedNullError;
 use types::{NativeSqlType, FromSql, ToSql, Array, IsNull};
 

diesel/src/types/impls/tuples.rs

@@ -1,11 +1,10 @@
 use expression::{Expression, SelectableExpression, NonAggregate};
 use persistable::InsertableColumns;
 use query_builder::{Changeset, QueryBuilder, BuildQueryResult};
-use query_source::QuerySource;
+use query_source::{QuerySource, Queriable, Table, Column};
 use row::Row;
 use std::error::Error;
 use types::{NativeSqlType, FromSqlRow, ToSql, Nullable};
-use {Queriable, Table, Column};
 
 // FIXME(https://github.com/rust-lang/rust/issues/19630) Remove this work-around
 macro_rules! e {

diesel_codegen/src/update.rs

@@ -106,7 +106,7 @@ fn save_changes_impl(
                     -> ::diesel::QueryResult<T> where
                     T: Queriable<$sql_type>,
                 {
-                    use ::diesel::query_builder::update;
+                    use ::diesel::update;
                     update($table.filter($table.primary_key().eq(&self.$pk_field)))
                         .set(self)
                         .get_result(&connection)

diesel_tests/tests/compile-fail/update_requires_column_be_from_same_table.rs

@@ -2,7 +2,6 @@
 extern crate diesel;
 
 use diesel::*;
-use diesel::query_builder::update;
 
 table! {
     users {

diesel_tests/tests/compile-fail/update_requires_left_side_of_eq_to_be_a_column.rs

@@ -3,7 +3,6 @@ extern crate diesel;
 
 use diesel::*;
 use diesel::expression::AsExpression;
-use diesel::query_builder::update;
 
 table! {
     users {

diesel_tests/tests/debug/mod.rs

@@ -1,6 +1,5 @@
 use diesel::*;
 use diesel::query_builder::debug::DebugQueryBuilder;
-use diesel::query_builder::update;
 
 #[test]
 fn test_debug_count_output() {

diesel_tests/tests/expressions/mod.rs

@@ -4,7 +4,7 @@ mod ops;
 use schema::{connection, NewUser};
 use schema::users::dsl::*;
 use diesel::*;
-use diesel::query_builder::*;
+use diesel::query_builder::{QueryBuilder, BuildQueryResult, AsQuery};
 use diesel::expression::dsl::*;
 
 #[test]

diesel_tests/tests/insert.rs

@@ -127,9 +127,8 @@ fn insert_borrowed_content() {
 }
 
 #[test]
-fn delete() {
+fn delete_records() {
     use schema::users::dsl::*;
-    use diesel::query_builder::delete;
     let connection = connection_with_sean_and_tess_in_users_table();
 
     let deleted_rows = delete(users.filter(name.eq("Sean"))).execute(&connection);

diesel_tests/tests/schema.rs

@@ -1,7 +1,5 @@
 use diesel::*;
 
-pub use diesel::query_builder::insert;
-
 #[derive(PartialEq, Eq, Debug, Clone, Queriable)]
 #[changeset_for(users)]
 #[has_many(posts)]

diesel_tests/tests/update.rs

@@ -1,6 +1,5 @@
 use schema::*;
 use diesel::*;
-use diesel::query_builder::update;
 
 #[test]
 fn test_updating_single_column() {