zh docs update

orm/docs/zh/Models.md

@@ -278,12 +278,12 @@ type Tag struct {
 
 设置对应的 rel 关系删除时，如何处理关系字段。
 
-```go
 	cascade        级联删除(默认值)
 	set_null       设置为 NULL，需要设置 null = true
 	set_default    设置为默认值，需要设置 default 值
 	do_nothing     什么也不做，忽略
 
+```go
 type User struct {
 	...
 	Profile *Profile `orm:"null;rel(one);on_delete(set_null)"`

orm/docs/zh/Object.md

@@ -1,58 +1,62 @@
 ## Object
 
-对 object 操作的三个方法 Insert / Update / Delete
+对 object 操作简单的三个方法 Read / Insert / Update / Delete
 ```go
 o := orm.NewOrm()
 user := NewUser()
 user.UserName = "slene"
 user.Password = "password"
 user.Email = "vslene@gmail.com"
-obj := o.Object(user)
-fmt.Println(obj.Insert())
+
+fmt.Println(o.Insert(user))
+
 user.UserName = "Your"
-fmt.Println(obj.Update())
-fmt.Println(obj.Delete())
+fmt.Println(o.Update(user))
+
+fmt.Println(o.Delete(user))
 ```
 ### Read
 ```go
-var user User
-err := o.QueryTable("user").Filter("id", 1).One(&user)
-if err != orm.ErrMultiRows {
-	fmt.Println(user.UserName)
+o := orm.NewOrm()
+user := User{Id: 1}
+
+o.Read(&user)
+
+if err == sql.ErrNoRows {
+	fmt.Println("查询不到")
+} else if err == orm.ErrMissPK {
+	fmt.Println("找不到主键")
+} else {
+	fmt.Println(user.Id, user.UserName)
 }
 ```
-### Create
+### Insert
 ```go
-profile := NewProfile()
-profile.Age = 30
-profile.Money = 9.8
-
-user := NewUser()
-user.Profile = profile
+o := orm.NewOrm()
+var user User
 user.UserName = "slene"
 user.Password = "password"
 user.Email = "vslene@gmail.com"
 user.IsActive = true
 
-fmt.Println(o.Object(profile).Insert())
-fmt.Println(o.Object(user).Insert())
+fmt.Println(o.Insert(&user))
 fmt.Println(user.Id)
 ```
 创建后会自动对 auto 的 field 赋值
 
 ### Update
 ```go
-var user User
-err := o.QueryTable("user").Filter("id", 1).One(&user)
-if err != orm.ErrMultiRows {
-	fmt.Println(user.UserName)
-}
+o := orm.NewOrm()
+user := User{Id: 1}
+if o.Read(&user) == nil {
 	user.UserName = "MyName"
-o.Object(&user).Update()
+	o.Update(&user)
+}
 ```
 ### Delete
 ```go
-o.Object(user).Delete()
+o := orm.NewOrm()
+o.Delete(&User{Id: 1})
 ```
 Delete 操作会对反向关系进行操作，此例中 Post 拥有一个到 User 的外键。删除 User 的时候。如果 on_delete 设置为默认的级联操作，将删除对应的 Post
 

orm/docs/zh/Orm.md

@@ -40,8 +40,8 @@ func main() {
 	user.Email = "vslene@gmail.com"
 	user.IsActive = true
 
-	fmt.Println(o.Object(profile).Insert())
-	fmt.Println(o.Object(user).Insert())
+	fmt.Println(o.Insert(profile))
+	fmt.Println(o.Insert(user))
 
 	var params []orm.Params
 	if cnt, err := o.QueryTable("user").RelatedSel().Limit(3).OrderBy("-id").Values(&params); err != nil {

orm/docs/zh/Query.md

@@ -126,6 +126,7 @@ qs.Filter("profile__isnull", false)
 qs.Filter("profile__isnull", true).Filter("user_name", "slene")
 // WHERE profile_id IS NULL AND user_name = 'slene'
 ```
+
 #### Exclude
 
 使用 `NOT` 排除条件
@@ -135,6 +136,9 @@ qs.Filter("profile__isnull", true).Filter("user_name", "slene")
 qs.Exclude("profile__isnull", true).Filter("user_name", "slene")
 // WHERE NOT profile_id IS NULL AND user_name = 'slene'
 ```
+
+#### SetCond
+
 #### Limit
 
 限制最大返回数据行数，第二个参数可以设置 `Offset`
@@ -157,6 +161,7 @@ qs.Limit(-1, 100)
 // LIMIT 18446744073709551615 OFFSET 100
 // 18446744073709551615 是 1<<64 - 1 用来指定无 limit 限制 但有 offset 偏移的情况
 ```
+
 #### Offset
 	
 设置 偏移行数
@@ -164,6 +169,7 @@ qs.Limit(-1, 100)
 qs.OFFSET(20)
 // LIMIT 1000 OFFSET 20
 ```
+
 #### OrderBy
 
 参数使用 **expr**
@@ -176,6 +182,7 @@ qs.OrderBy("id", "-profile__age")
 qs.OrderBy("-profile__money", "profile")
 // ORDER BY profile.money DESC, profile_id ASC
 ```
+
 #### RelatedSel
 
 关系查询，参数使用 **expr**
@@ -193,15 +200,132 @@ qs.RelateSel("user")
 
 // 对设置 null 属性的 Field 将使用 LEFT OUTER JOIN
 ```
-#### Count
 
-查询当前条件下的行数
+#### Count
+依据当前的查询条件，返回结果行数
 ```go
-o.QueryTable("user").Count() // SELECT COUNT(*) FROM USER
+cnt, err := o.QueryTable("user").Count() // SELECT COUNT(*) FROM USER
+fmt.Printf("Count Num: %s, %s", cnt, err)
 ```
 
-
-
+#### Update
+依据当前查询条件，进行批量更新操作
+```go
+num, err := o.QueryTable("user").Filter("user_name", "slene").Update(orm.Params{
+	"user_name": "astaxie",
+})
+fmt.Printf("Affected Num: %s, %s", num, err)
+// SET user_name = "astaixe" WHERE user_name = "slene"
+```
+
+#### Delete
+依据当前查询条件，进行批量删除操作
+```go
+num, err := o.QueryTable("user").Filter("user_name", "slene").Delete()
+fmt.Printf("Affected Num: %s, %s", num, err)
+// DELETE FROM user WHERE user_name = "slene"
+```
+
+#### All
+返回对应的结果集对象
+```go
+var users []*User
+num, err := o.QueryTable("user").Filter("user_name", "slene").All(&users)
+fmt.Printf("Returned Rows Num: %s, %s", num, err)
+```
+
+#### One
+尝试返回单个对象
+```go
+var user *User
+err := o.QueryTable("user").Filter("user_name", "slene").One(&user)
+if err == orm.ErrMultiRows {
+	fmt.Printf("Returned Multi Rows Not One")
+}
+```
+
+#### Values
+返回结果集的 key => value 值
+
+key 为 Model 里的 Field name，value 的值 以 string 保存
+
+```go
+var maps []orm.Params
+num, err := o.QueryTable("user").Values(&maps)
+if err != nil {
+	fmt.Printf("Result Nums: %d\n", num)
+	for _, m := range maps {
+		fmt.Println(m["Id"], m["UserName"])
+	}
+}
+```
+
+返回指定的 Field 数据
+
+**TODO**: 暂不支持级联查询 **RelatedSel** 直接返回 Values
+
+但可以直接指定 expr 级联返回需要的数据
+
+```go
+var maps []orm.Params
+num, err := o.QueryTable("user").Values(&maps, "id", "user_name", "profile", "profile__age")
+if err != nil {
+	fmt.Printf("Result Nums: %d\n", num)
+	for _, m := range maps {
+		fmt.Println(m["Id"], m["UserName"], m["Profile"], m["Profile__Age"])
+		// map 中的数据都是展开的，没有复杂的嵌套
+	}
+}
+```
+
+#### ValuesList
+
+顾名思义，返回的结果集以slice存储
+
+结果的排列与 Model 中定义的 Field 顺序一致
+
+返回的每个元素值以 string 保存
+
+```go
+var lists []orm.ParamsList
+num, err := o.QueryTable("user").ValuesList(&lists)
+if err != nil {
+	fmt.Printf("Result Nums: %d\n", num)
+	for _, row := range lists {
+		fmt.Println(row)
+	}
+}
+```
+
+当然也可以指定 expr 返回指定的 Field
+
+```go
+var lists []orm.ParamsList
+num, err := o.QueryTable("user").ValuesList(&lists, "user_name", "profile__age")
+if err != nil {
+	fmt.Printf("Result Nums: %d\n", num)
+	for _, row := range lists {
+		fmt.Printf("UserName: %s, Age: %s\m", row[0], row[1])
+	}
+}
+```
+
+#### ValuesFlat
+
+只返回特定的 Field 值，讲结果集展开到单个 slice 里
+
+```go
+var list orm.ParamsList
+num, err := o.QueryTable("user").ValuesFlat(&list, "user_name")
+if err != nil {
+	fmt.Printf("Result Nums: %d\n", num)
+	fmt.Printf("All User Names: %s", strings.Join(list, ", ")
+}
+```
+
+#### PrepareInsert
+
+用于批量插入 prepare -> insert -> insert
 
 
 

orm/docs/zh/README.md

@@ -18,18 +18,9 @@ type User struct {
 	orm.Manager
 }
 
-type Post struct {
-	Id      int    `orm:"auto"`
-	User    *User  `orm:"rel(fk)"`
-	Title   string `orm:"size(100)"`
-	Content string
-	orm.Manager
-}
-
 func init() {
 	// 将表定义注册到 orm 里
 	orm.RegisterModel(new(User))
-	orm.RegisterModel(new(Post))
 
 	// 链接参数设置
 	orm.RegisterDataBase("default", "mysql", "root:root@/my_db?charset=utf8", 30)
@@ -40,39 +31,24 @@ func main() {
 
 	o := orm.NewOrm()
 
-	var user User
-	obj := o.Object(&user)
+	user := User{Name: "slene"}
 
 	// 创建
-	user.Name = "slene"
-	id, err := obj.Insert()
+	id, err := o.Insert(&user)
 	fmt.Println(id, err)
 
 	// 更新
 	user.Name = "astaxie"
-	num, err := obj.Update()
+	num, err := o.Update(&user)
 	fmt.Println(num, err)
 
 	// 查询单个
-	var u User
-	err = o.QueryTable("user").Filter("id", &user).One(&u)
-	fmt.Println(u.Id, u.Name, err)
-
-	// 创建 post
-	var post Post
-	post.Title = "beego orm"
-	post.Content = "powerful amazing"
-	post.User = &u
-	id, err = o.Object(&post).Insert()
-	fmt.Println(id, err)
-	
-	// 当然，以 map[string]interface{} 形式的数据返回也是允许的
-	var maps []orm.Params
-	num, err = o.QueryTable("user").Filter("id", &u).Values(&maps)
-	fmt.Println(num, err, maps[0])
+	u := User{Id: user.Id}
+	err = o.Read(&u)
+	fmt.Println(u.Name, err)
 
 	// 删除
-	num, err = obj.Delete() // 默认，级联删除 user 以及关系存在的 post
+	num, err = o.Delete(&u)
 	fmt.Println(num, err)
 }
 ```