Move examples in ad hoc file.

backup.go

@@ -18,18 +18,6 @@ import (
 
 // Backup/Copy the content of one database (source) to another (destination).
 // The database name is "main", "temp", or the name specified in an ATTACH statement.
-// Example:
-//	bck, err := sqlite.NewBackup(dst, "main", src, "main")
-//	// check err
-//	cbs := make(chan sqlite.BackupStatus)
-//	go func() {
-//		for {
-//			s := <- cbs
-//			// report progress
-//		}
-//	}()
-//	err = bck.Run(100, 250000, cbs)
-//	check(err)
 //
 // (See http://sqlite.org/c3ref/backup_finish.html#sqlite3backupinit)
 func NewBackup(dst *Conn, dstDbName string, src *Conn, srcDbName string) (*Backup, error) {
@@ -97,6 +85,9 @@ func (b *Backup) Run(npage int, sleepNs time.Duration, c chan<- BackupStatus) er
 	if err != Done {
 		b.Close()
 	} else {
+		if c != nil {
+			c <- b.Status()
+		}
 		err = b.Close()
 	}
 	if err != nil && err != Done {

backup_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

bench_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

blob.go

@@ -29,28 +29,11 @@ type BlobReadWriter struct {
 }
 
 // Zeroblobs are used to reserve space for a BLOB that is later written.
-//
-// Example:
-//	s, err := db.Prepare("INSERT INTO test VALUES (?)")
-//	// check err
-//	defer s.Finalize()
-//	err = s.Exec(ZeroBlobLength(10))
-//	// check err
 type ZeroBlobLength int
 
 // Open a BLOB for incremental I/O
-// Example:
-//	br, err := db.NewBlobReader("db_name", "table_name", "column_name", rowid)
-//  // check err
-//	defer br.Close()
-//	size, err := br.Size()
-//  // check err
-//	content = make([]byte, size)
-//	n, err = br.Read(content)
-//  // check err
 //
 // (See http://sqlite.org/c3ref/blob_open.html)
-// TODO A real 'incremental' example...
 func (c *Conn) NewBlobReader(db, table, column string, row int64) (*BlobReader, error) {
 	bl, err := c.blob_open(db, table, column, row, false)
 	if err != nil {

blob_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

busy_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

cache_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

date_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

driver_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

example_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package sqlite_test
+
+import (
+	"fmt"
+	sqlite "github.com/gwenn/gosqlite"
+)
+
+func check(err error) {
+	if err != nil {
+		panic(err)
+	}
+}
+
+func Example() {
+	db, err := sqlite.Open("") // path to db or "" for temp db
+	check(err)
+	defer db.Close()
+	err = db.Exec("CREATE TABLE test(id INTEGER PRIMARY KEY NOT NULL, name TEXT NOT NULL UNIQUE); -- ... and other ddls separated by semi-colon")
+	check(err)
+	ins, err := db.Prepare("INSERT INTO test (name) VALUES (?)")
+	check(err)
+	defer ins.Finalize()
+	_, err = ins.Insert("gosqlite driver")
+	check(err)
+	s, err := db.Prepare("SELECT name from test WHERE name like ?", "%go%")
+	check(err)
+	defer s.Finalize()
+	var name string
+	err = s.Select(func(s *sqlite.Stmt) (err error) {
+		if err = s.Scan(&name); err != nil {
+			return
+		}
+		fmt.Printf("%s\n", name)
+		return
+	})
+	// Output: gosqlite driver
+}
+
+func ExampleOpen() {
+	db, err := sqlite.Open(":memory:")
+	check(err)
+	defer db.Close()
+	fmt.Printf("db path: %q\n", db.Filename)
+	// Output: db path: ":memory:"
+}
+
+func ExampleConn_Exec() {
+	db, err := sqlite.Open("")
+	check(err)
+	defer db.Close()
+
+	err = db.Exec("CREATE TABLE test1 (content TEXT); CREATE TABLE test2 (content TEXT); INSERT INTO test1 VALUES ('DATA')")
+	check(err)
+	tables, err := db.Tables()
+	check(err)
+	fmt.Printf("%d tables\n", len(tables))
+	// Output: 2 tables
+}
+
+func ExampleStmt_ExecDml() {
+	db, err := sqlite.Open("")
+	check(err)
+	defer db.Close()
+	err = db.Exec("CREATE TABLE test (content TEXT); INSERT INTO test VALUES ('Go'); INSERT INTO test VALUES ('SQLite')")
+	check(err)
+
+	s, err := db.Prepare("UPDATE test SET content = content || 'lang' where content like ?")
+	check(err)
+	defer s.Finalize()
+	changes, err := s.ExecDml("%o")
+	check(err)
+	fmt.Printf("%d change(s)\n", changes)
+	// Output: 1 change(s)
+}
+
+func ExampleStmt_Insert() {
+	db, err := sqlite.Open("")
+	check(err)
+	defer db.Close()
+	err = db.Exec("CREATE TABLE test (content TEXT)")
+	check(err)
+
+	s, err := db.Prepare("INSERT INTO test VALUES (?)")
+	check(err)
+	defer s.Finalize()
+	data := []string{"Go", "SQLite", "Driver"}
+	for _, d := range data {
+		rowId, err := s.Insert(d)
+		check(err)
+		fmt.Printf("%d\n", rowId)
+	}
+	// Output: 1
+	// 2
+	// 3
+}
+
+func ExampleStmt_NamedScan() {
+	db, err := sqlite.Open("")
+	check(err)
+	defer db.Close()
+
+	s, err := db.Prepare("SELECT 1 as id, 'Go' as name UNION SELECT 2, 'SQLite'")
+	check(err)
+	defer s.Finalize()
+
+	var id int
+	var name string
+	err = s.Select(func(s *sqlite.Stmt) (err error) {
+		if err = s.NamedScan("name", &name, "id", &id); err != nil {
+			return
+		}
+		fmt.Println(id, name)
+		return
+	})
+	// Output: 1 Go
+	// 2 SQLite
+}
+
+func ExampleStmt_Scan() {
+	db, err := sqlite.Open("")
+	check(err)
+	defer db.Close()
+
+	s, err := db.Prepare("SELECT 1 as id, 'Go' as name UNION SELECT 2, 'SQLite'")
+	check(err)
+	defer s.Finalize()
+
+	var id int
+	var name string
+	err = s.Select(func(s *sqlite.Stmt) (err error) {
+		if err = s.Scan(&id, &name); err != nil {
+			return
+		}
+		fmt.Println(id, name)
+		return
+	})
+	// Output: 1 Go
+	// 2 SQLite
+}
+
+func ExampleNewBackup() {
+	dst, err := sqlite.Open("")
+	check(err)
+	defer dst.Close()
+	src, err := sqlite.Open("")
+	check(err)
+	defer src.Close()
+	err = src.Exec("CREATE TABLE test (content BLOB); INSERT INTO test VALUES (zeroblob(100))")
+	check(err)
+
+	bck, err := sqlite.NewBackup(dst, "main", src, "main")
+	check(err)
+	defer bck.Close()
+
+	cbs := make(chan sqlite.BackupStatus)
+	ack := make(chan bool)
+	go func() {
+		for {
+			s := <-cbs
+			fmt.Printf("backup progress (remaining: %d)\n", s.Remaining)
+			ack <- true
+		}
+	}()
+	err = bck.Run(100, 250000, cbs)
+	check(err)
+	<-ack
+	// Output: backup progress (remaining: 0)
+}
+
+func ExampleConn_NewBlobReader() {
+	db, err := sqlite.Open("")
+	check(err)
+	err = db.Exec("CREATE TABLE test (content BLOB); INSERT INTO test VALUES (zeroblob(10))")
+	check(err)
+	rowid := db.LastInsertRowid()
+
+	br, err := db.NewBlobReader("main", "test", "content", rowid)
+	check(err)
+	defer br.Close()
+	size, err := br.Size()
+	check(err)
+	// TODO A real 'incremental' example...
+	content := make([]byte, size)
+	n, err := br.Read(content)
+	check(err)
+	fmt.Printf("blob (size: %d, read: %d, content: %q\n", size, n, content)
+	// Output: blob (size: 10, read: 10, content: "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
+}

function.c

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 #include <sqlite3.h>
 #include <stdlib.h>
 #include "_cgo_export.h"

function_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

meta_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

pragma_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

sqlite.go

@@ -3,31 +3,6 @@
 // license that can be found in the LICENSE file.
 
 // Package sqlite provides access to the SQLite library, version 3.
-//
-// Simple example:
-//	db, err := sqlite.Open("/path/to/db")
-//	if err != nil {
-//		...
-//	}
-//	defer db.Close()
-//  err = db.Exec("CREATE TABLE test(id INTEGER PRIMARY KEY NOT NULL, name TEXT NOT NULL UNIQUE); -- ... and other ddls separated by semi-colon")
-//  ...
-//  ins, err := db.Prepare("INSERT INTO test (name) VALUES (?)")
-//  if err != nil {
-//    ...
-//	}
-//	defer ins.Finalize()
-//  rowId, err := ins.Insert("Bart")
-//  ...
-//	s, err := db.Prepare("SELECT name from test WHERE name like ?", "%a%")
-//  ...
-//  defer s.Finalize()
-//  var name string
-//  err = s.Select(func(s *Stmt) (err error) {
-//		err = s.Scan(&name)
-//      ...
-//		fmt.Printf("%s\n", name)
-//	})
 package sqlite
 
 /*
@@ -221,13 +196,6 @@ const (
 // ":memory:" for memory db
 // "" for temp file db
 //
-// Example:
-//	db, err := sqlite.Open(":memory:")
-//	if err != nil {
-//		...
-//	}
-//	defer db.Close()
-//
 // (See sqlite3_open_v2: http://sqlite.org/c3ref/open.html)
 func Open(filename string, flags ...OpenFlag) (*Conn, error) {
 	return OpenVfs(filename, "", flags...)
@@ -307,10 +275,6 @@ func (c *Conn) EnableExtendedResultCodes(b bool) error {
 
 // Prepare and execute one parameterized statement or many statements (separated by semi-colon).
 // Don't use it with SELECT or anything that returns data.
-//
-// Example:
-//	err := db.Exec("CREATE TABLE test(id INTEGER PRIMARY KEY NOT NULL, name TEXT NOT NULL); -- ...")
-//
 func (c *Conn) Exec(cmd string, args ...interface{}) error {
 	for len(cmd) > 0 {
 		s, err := c.prepare(cmd)

sqlite_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (

stmt.go

@@ -111,13 +111,6 @@ func (c *Conn) prepare(cmd string, args ...interface{}) (*Stmt, error) {
 
 // First look in the statement cache or compile the SQL statement.
 // And optionally bind values.
-// Example:
-//	stmt, err := db.Prepare("SELECT 1 where 1 = ?", 1)
-//	if err != nil {
-//		...
-//	}
-//	defer stmt.Finalize()
-//
 // (See sqlite3_prepare_v2: http://sqlite.org/c3ref/prepare.html)
 func (c *Conn) Prepare(cmd string, args ...interface{}) (*Stmt, error) {
 	s := c.stmtCache.find(cmd)
@@ -448,21 +441,7 @@ func (s *Stmt) ColumnType(index int) Type {
 	return Type(C.sqlite3_column_type(s.stmt, C.int(index)))
 }
 
-// Scan result values from a query by name (name1, value1, ...)
-// Example:
-//	stmt, err := db.Prepare("SELECT 1 as id, 'test' as name")
-//	// TODO error handling
-//	defer stmt.Finalize()
-//	var id int
-//	var name string
-//  err = s.Select(func(s *Stmt) (err error) {
-//		if err = stmt.NamedScan("name", &name, "id", &id); err != nil {
-//			return
-//      }
-//		fmt.Println(id, name)
-//  	return
-//  })
-//	// TODO error handling
+// Scan result values from a query by name (name1, value1, ...).
 //
 // NULL value is converted to 0 if arg type is *int,*int64,*float,*float64, to "" for *string, to []byte{} for *[]byte and to false for *bool.
 // Calls sqlite3_column_(blob|double|int|int64|text) depending on args type.
@@ -489,21 +468,7 @@ func (s *Stmt) NamedScan(args ...interface{}) error {
 	return nil
 }
 
-// Scan result values from a query
-// Example:
-//	stmt, err := db.Prepare("SELECT 1, 'test'")
-//	// TODO error handling
-//	defer stmt.Finalize()
-//	var id int
-//	var name string
-//  err = s.Select(func(s *Stmt) error {
-//		if err = stmt.Scan(&id, &name); err != nil {
-//			return
-//      }
-//		fmt.Println(id, name)
-//  	return
-//  })
-//	// TODO error handling
+// Scan result values from a query.
 //
 // NULL value is converted to 0 if arg type is *int,*int64,*float,*float64, to "" for *string, to []byte{} for *[]byte and to false for *bool.
 // To avoid NULL conversion, arg type must be **T

trace_test.go

+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package sqlite_test
 
 import (