Skip to content

Commit

Permalink
Update godoc
Browse files Browse the repository at this point in the history
  • Loading branch information
@jinzhu
jinzhu committed Mar 7, 2016
1 parent 779c4d4 commit 88184a9
Show file tree
Hide file tree
Showing 9 changed files with 87 additions and 82 deletions.
18 changes: 9 additions & 9 deletions callback.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@ import (
// DefaultCallback default callbacks defined by gorm
var DefaultCallback = &Callback{}

// Callback contains callbacks that used when CURD objects
// Field `creates` hold callbacks will be call when creating object
// Field `updates` hold callbacks will be call when updating object
// Field `deletes` hold callbacks will be call when deleting object
// Field `queries` hold callbacks will be call when querying object with query methods like Find, First, Related, Association...
// Field `rowQueries` hold callbacks will be call when querying object with Row, Rows...
// Field `processors` hold all callback processors, will be used to generate above callbacks in order
// Callback is a struct that contains all CURD callbacks
// Field `creates` contains callbacks will be call when creating object
// Field `updates` contains callbacks will be call when updating object
// Field `deletes` contains callbacks will be call when deleting object
// Field `queries` contains callbacks will be call when querying object with query methods like Find, First, Related, Association...
// Field `rowQueries` contains callbacks will be call when querying object with Row, Rows...
// Field `processors` contains all callback processors, will be used to generate above callbacks in order
type Callback struct {
creates []*func(scope *Scope)
updates []*func(scope *Scope)
Expand All @@ -23,7 +23,7 @@ type Callback struct {
processors []*CallbackProcessor
}

// CallbackProcessor contains all informations for a callback
// CallbackProcessor contains callback informations
type CallbackProcessor struct {
name string // current callback's name
before string // register current callback before a callback
Expand Down Expand Up @@ -68,7 +68,7 @@ func (c *Callback) Delete() *CallbackProcessor {
}

// Query could be used to register callbacks for querying objects with query methods like `Find`, `First`, `Related`, `Association`...
// refer `Create` for usage
// Refer `Create` for usage
func (c *Callback) Query() *CallbackProcessor {
return &CallbackProcessor{kind: "query", parent: c}
}
Expand Down
2 changes: 1 addition & 1 deletion dialect.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ type Dialect interface {
// HasColumn check has column or not
HasColumn(tableName string, columnName string) bool

// LimitAndOffsetSQL return generate SQL with limit and offset, as mssql has special case
// LimitAndOffsetSQL return generated SQL with Limit and Offset, as mssql has special case
LimitAndOffsetSQL(limit, offset int) string
// SelectFromDummyTable return select values, for most dbs, `SELECT values` just works, mysql needs `SELECT value FROM DUAL`
SelectFromDummyTable() string
Expand Down
4 changes: 2 additions & 2 deletions errors.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ import (
)

var (
// ErrRecordNotFound record not found, happens when you are looking up with a struct, and haven't find any matched data
// ErrRecordNotFound record not found error, happens when haven't find any matched data when looking up with a struct
ErrRecordNotFound = errors.New("record not found")
// ErrInvalidSQL invalid SQL, happens when you passed invalid SQL
// ErrInvalidSQL invalid SQL error, happens when you passed invalid SQL
ErrInvalidSQL = errors.New("invalid SQL")
// ErrInvalidTransaction invalid transaction when you are trying to `Commit` or `Rollback`
ErrInvalidTransaction = errors.New("no valid transaction")
Expand Down
89 changes: 49 additions & 40 deletions main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,17 @@ type DB struct {
joinTableHandlers map[string]JoinTableHandler
}

// Open open a new db connection, need to import driver first, for example:
// Open initialize a new db connection, need to import driver first, e.g:
//
// import _ "github.com/go-sql-driver/mysql"
// func main() {
// db, err := gorm.Open("mysql", "user:password@/dbname?charset=utf8&parseTime=True&loc=Local")
// }
// GORM has wrapped some drivers, for easier to remember its name, so you could import the mysql driver with
// GORM has wrapped some drivers, for easier to remember driver's import path, so you could import the mysql driver with
// import _ "github.com/jinzhu/gorm/dialects/mysql"
// // import _ "github.com/jinzhu/gorm/dialects/postgres"
// // import _ "github.com/jinzhu/gorm/dialects/sqlite"
// // import _ "github.com/jinzhu/gorm/dialects/mssql"
func Open(dialect string, args ...interface{}) (*DB, error) {
var db DB
var err error
Expand Down Expand Up @@ -87,7 +90,7 @@ func (s *DB) DB() *sql.DB {
return s.db.(*sql.DB)
}

// New initialize a new db connection without any search conditions
// New clone a new db connection without search conditions
func (s *DB) New() *DB {
clone := s.clone()
clone.search = nil
Expand All @@ -102,16 +105,14 @@ func (s *DB) NewScope(value interface{}) *Scope {
return &Scope{db: dbClone, Search: dbClone.search.clone(), Value: value}
}

// CommonDB return the underlying sql.DB or sql.Tx instance.
// Use of this method is discouraged. It's mainly intended to allow
// coexistence with legacy non-GORM code.
// CommonDB return the underlying `*sql.DB` or `*sql.Tx` instance, mainly intended to allow coexistence with legacy non-GORM code.
func (s *DB) CommonDB() sqlCommon {
return s.db
}

// Callback return Callbacks container, you could add/remove/change callbacks with it
// Callback return `Callbacks` container, you could add/change/delete callbacks with it
// db.Callback().Create().Register("update_created_at", updateCreated)
// Refer: https://jinzhu.github.io/gorm/development.html#callbacks for more
// Refer https://jinzhu.github.io/gorm/development.html#callbacks
func (s *DB) Callback() *Callback {
s.parent.callbacks = s.parent.callbacks.clone()
return s.parent.callbacks
Expand All @@ -138,17 +139,17 @@ func (s *DB) SingularTable(enable bool) {
s.parent.singularTable = enable
}

// Where return a new relation, accepts use `map`, `struct` or `string` as conditions, refer http://jinzhu.github.io/gorm/curd.html#query
// Where return a new relation, filter records with given conditions, accepts `map`, `struct` or `string` as conditions, refer http://jinzhu.github.io/gorm/curd.html#query
func (s *DB) Where(query interface{}, args ...interface{}) *DB {
return s.clone().search.Where(query, args...).db
}

// Or match before conditions or this one, similar to `Where`
// Or filter records that match before conditions or this one, similar to `Where`
func (s *DB) Or(query interface{}, args ...interface{}) *DB {
return s.clone().search.Or(query, args...).db
}

// Not don't match current conditions, similar to `Where`
// Not filter records that don't match current conditions, similar to `Where`
func (s *DB) Not(query interface{}, args ...interface{}) *DB {
return s.clone().search.Not(query, args...).db
}
Expand All @@ -163,18 +164,18 @@ func (s *DB) Offset(offset int) *DB {
return s.clone().search.Offset(offset).db
}

// Order specify order when retrieve records from database, pass `true` as the second argument to overwrite `Order` conditions
// Order specify order when retrieve records from database, set reorder to `true` to overwrite defined conditions
func (s *DB) Order(value string, reorder ...bool) *DB {
return s.clone().search.Order(value, reorder...).db
}

// Select When querying, specify fields that you want to retrieve from database, by default, will select all fields;
// Select specify fields that you want to retrieve from database when querying, by default, will select all fields;
// When creating/updating, specify fields that you want to save to database
func (s *DB) Select(query interface{}, args ...interface{}) *DB {
return s.clone().search.Select(query, args...).db
}

// Omit specify fields that you want to ignore when save to database when creating/updating
// Omit specify fields that you want to ignore when saving to database for creating, updating
func (s *DB) Omit(columns ...string) *DB {
return s.clone().search.Omit(columns...).db
}
Expand All @@ -196,15 +197,26 @@ func (s *DB) Joins(query string, args ...interface{}) *DB {
}

// Scopes pass current database connection to arguments `func(*DB) *DB`, which could be used to add conditions dynamically
// Refer https://jinzhu.github.io/gorm/curd.html#scopes for more
// func AmountGreaterThan1000(db *gorm.DB) *gorm.DB {
// return db.Where("amount > ?", 1000)
// }
//
// func OrderStatus(status []string) func (db *gorm.DB) *gorm.DB {
// return func (db *gorm.DB) *gorm.DB {
// return db.Scopes(AmountGreaterThan1000).Where("status in (?)", status)
// }
// }
//
// db.Scopes(AmountGreaterThan1000, OrderStatus([]string{"paid", "shipped"})).Find(&orders)
// Refer https://jinzhu.github.io/gorm/curd.html#scopes
func (s *DB) Scopes(funcs ...func(*DB) *DB) *DB {
for _, f := range funcs {
s = f(s)
}
return s
}

// Unscoped return all record including deleted record, refer Soft Delete https://jinzhu.github.io/gorm/curd.html#scopes
// Unscoped return all record including deleted record, refer Soft Delete https://jinzhu.github.io/gorm/curd.html#soft-delete
func (s *DB) Unscoped() *DB {
return s.clone().search.unscoped().db
}
Expand Down Expand Up @@ -245,12 +257,12 @@ func (s *DB) Scan(dest interface{}) *DB {
return s.clone().NewScope(s.Value).Set("gorm:query_destination", dest).callCallbacks(s.parent.callbacks.queries).db
}

// Row return `*sql.Row` with given condtions
// Row return `*sql.Row` with given conditions
func (s *DB) Row() *sql.Row {
return s.NewScope(s.Value).row()
}

// Rows return `*sql.Rows` with given condtions
// Rows return `*sql.Rows` with given conditions
func (s *DB) Rows() (*sql.Rows, error) {
return s.NewScope(s.Value).rows()
}
Expand All @@ -271,6 +283,8 @@ func (s *DB) ScanRows(rows *sql.Rows, result interface{}) error {
}

// Pluck used to query single column from a model as a map
// var ages []int64
// db.Find(&users).Pluck("age", &ages)
func (s *DB) Pluck(column string, value interface{}) *DB {
return s.NewScope(s.Value).pluck(column, value).db
}
Expand All @@ -286,6 +300,7 @@ func (s *DB) Related(value interface{}, foreignKeys ...string) *DB {
}

// FirstOrInit find first matched record or initalize a new one with given conditions (only works with struct, map conditions)
// https://jinzhu.github.io/gorm/curd.html#firstorinit
func (s *DB) FirstOrInit(out interface{}, where ...interface{}) *DB {
c := s.clone()
if result := c.First(out, where...); result.Error != nil {
Expand All @@ -300,6 +315,7 @@ func (s *DB) FirstOrInit(out interface{}, where ...interface{}) *DB {
}

// FirstOrCreate find first matched record or create a new one with given conditions (only works with struct, map conditions)
// https://jinzhu.github.io/gorm/curd.html#firstorcreate
func (s *DB) FirstOrCreate(out interface{}, where ...interface{}) *DB {
c := s.clone()
if result := c.First(out, where...); result.Error != nil {
Expand Down Expand Up @@ -340,7 +356,7 @@ func (s *DB) UpdateColumns(values interface{}) *DB {
callCallbacks(s.parent.callbacks.updates).db
}

// Save update the value in database, if the value doesn't have primary key, will insert it
// Save update value in database, if the value doesn't have primary key, will insert it
func (s *DB) Save(value interface{}) *DB {
scope := s.clone().NewScope(value)
if scope.PrimaryKeyZero() {
Expand All @@ -355,7 +371,7 @@ func (s *DB) Create(value interface{}) *DB {
return scope.callCallbacks(s.parent.callbacks.creates).db
}

// Delete delete value that match given conditions, if the value has primary key, then will including the primary key as condition
// Delete delete value match given conditions, if the value has primary key, then will including the primary key as condition
func (s *DB) Delete(value interface{}, where ...interface{}) *DB {
return s.clone().NewScope(value).inlineCondition(where...).callCallbacks(s.parent.callbacks.deletes).db
}
Expand Down Expand Up @@ -432,14 +448,19 @@ func (s *DB) Rollback() *DB {
return s
}

// NewRecord check if value's primary key is blank or not
// NewRecord check if value's primary key is blank
func (s *DB) NewRecord(value interface{}) bool {
return s.clone().NewScope(value).PrimaryKeyZero()
}

// RecordNotFound check if returning record not found error
// RecordNotFound check if returning ErrRecordNotFound error
func (s *DB) RecordNotFound() bool {
return s.Error == ErrRecordNotFound
for _, err := range s.GetErrors() {
if err == ErrRecordNotFound {
return true
}
}
return false
}

// CreateTable create table for models
Expand All @@ -464,19 +485,6 @@ func (s *DB) DropTable(values ...interface{}) *DB {
return db
}

// DropTableIfExists drop table for models only when it exists
func (s *DB) DropTableIfExists(values ...interface{}) *DB {
db := s.clone()
for _, value := range values {
if tableName, ok := value.(string); ok {
db = db.Table(tableName)
}

db = db.NewScope(value).dropTableIfExists().db
}
return db
}

// HasTable check has table or not
func (s *DB) HasTable(value interface{}) bool {
var (
Expand Down Expand Up @@ -539,8 +547,8 @@ func (s *DB) RemoveIndex(indexName string) *DB {
return scope.db
}

// AddForeignKey Add foreign key to the given scope
// Example: db.Model(&User{}).AddForeignKey("city_id", "cities(id)", "RESTRICT", "RESTRICT")
// AddForeignKey Add foreign key to the given scope, e.g:
// db.Model(&User{}).AddForeignKey("city_id", "cities(id)", "RESTRICT", "RESTRICT")
func (s *DB) AddForeignKey(field string, dest string, onDelete string, onUpdate string) *DB {
scope := s.clone().NewScope(s.Value)
scope.addForeignKey(field, dest, onDelete, onUpdate)
Expand Down Expand Up @@ -569,7 +577,8 @@ func (s *DB) Association(column string) *Association {
return &Association{Error: err}
}

// Preload preload column with given conditions
// Preload preload associations with given conditions
// db.Preload("Orders", "state NOT IN (?)", "cancelled").Find(&users)
func (s *DB) Preload(column string, conditions ...interface{}) *DB {
return s.clone().search.Preload(column, conditions...).db
}
Expand Down Expand Up @@ -631,7 +640,7 @@ func (s *DB) AddError(err error) error {
return err
}

// GetErrors get happened errors for the db
// GetErrors get happened errors from the db
func (s *DB) GetErrors() (errors []error) {
if errs, ok := s.Error.(errorsInterface); ok {
return errs.GetErrors()
Expand Down
5 changes: 4 additions & 1 deletion model.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,10 @@ package gorm

import "time"

// Model base model definition, including `ID`, `CreatedAt`, `UpdatedAt`, `DeletedAt`, which could be embeded in your models
// Model base model definition, including fields `ID`, `CreatedAt`, `UpdatedAt`, `DeletedAt`, which could be embeded in your models
// type User struct {
// gorm.Model
// }
type Model struct {
ID uint `gorm:"primary_key"`
CreatedAt time.Time
Expand Down
2 changes: 1 addition & 1 deletion model_struct.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ func getForeignField(column string, fields []*StructField) *StructField {
return nil
}

// GetModelStruct generate model struct & relationships based on struct and tag definition
// GetModelStruct get value's model struct, relationships based on struct and tag definition
func (scope *Scope) GetModelStruct() *ModelStruct {
var modelStruct ModelStruct
// Scope value can't be nil
Expand Down
Loading

0 comments on commit 88184a9

Please sign in to comment.