From 94845326b5ccd208ef357a6958f23ff3572f46d8 Mon Sep 17 00:00:00 2001 From: Dave Collins Date: Tue, 8 Jul 2014 01:41:39 -0500 Subject: [PATCH] Use testable example and update doc.go README.md. This commit moves the ProcessBlock example to a test file so it integrates nicely with Go's example tooling. This allows the example output to be tested as a part of running the normal Go tests to help ensure it doesn't get out of date with the code. It is also nice to have the example in one place rather than repeating it in doc.go and README.md. Links and information about the example have been incldued in doc.go and README.md in place of the example. --- README.md | 59 ++++++------------------------------------------- doc.go | 56 +++++----------------------------------------- example_test.go | 59 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 72 insertions(+), 102 deletions(-) create mode 100644 example_test.go diff --git a/README.md b/README.md index 53ebef6b..180afa8c 100644 --- a/README.md +++ b/README.md @@ -73,59 +73,14 @@ is by no means exhaustive: coins - Insert the block into the block database -## Block Processing Example +## Examples -The following example program demonstrates processing a block. This example -intentionally causes an error by attempting to process a duplicate block. - -```Go - package main - - import ( - "fmt" - "github.com/conformal/btcchain" - "github.com/conformal/btcdb" - _ "github.com/conformal/btcdb/memdb" - "github.com/conformal/btcnet" - "github.com/conformal/btcutil" - ) - - func main() { - // Create a new database to store the accepted blocks into. Typically - // this would be opening an existing database and would not use memdb - // which is a memory-only database backend, but we create a new db - // here so this is a complete working example. - db, err := btcdb.CreateDB("memdb") - if err != nil { - fmt.Printf("Failed to create database: %v\n", err) - return - } - defer db.Close() - - // Insert the main network genesis block. This is part of the initial - // database setup. Like above, this typically would not be needed when - // opening an existing database. - genesisBlock := btcutil.NewBlock(btcnet.MainNetParams.GenesisBlock) - _, err = db.InsertBlock(genesisBlock) - if err != nil { - fmt.Printf("Failed to insert genesis block: %v\n", err) - return - } - - // Create a new BlockChain instance using the underlying database for - // the main bitcoin network and ignore notifications. - chain := btcchain.New(db, &btcnet.MainNetParams, nil) - - // Process a block. For this example, we are going to intentionally - // cause an error by trying to process the genesis block which already - // exists. - _, err = chain.ProcessBlock(genesisBlock, btcchain.BFNone) - if err != nil { - fmt.Printf("Failed to process block: %v\n", err) - return - } - } -``` +* [ProcessBlock Example] + (http://godoc.org/github.com/conformal/btcchain#example-ProcessBlock) + Demonstrates how to create a new chain instance and use ProcessBlock to + attempt to attempt add a block to the chain. This example intentionally + attempts to insert a duplicate genesis block to illustrate how an invalid + block is handled. ## TODO diff --git a/doc.go b/doc.go index 4db9322d..f9909cb4 100644 --- a/doc.go +++ b/doc.go @@ -61,57 +61,13 @@ is by no means exhaustive: coins - Insert the block into the block database -Block Processing Example +Examples -The following example program demonstrates processing a block. This example -intentionally causes an error by attempting to process a duplicate block. - - package main - - import ( - "fmt" - "github.com/conformal/btcchain" - "github.com/conformal/btcdb" - _ "github.com/conformal/btcdb/memdb" - "github.com/conformal/btcnet" - "github.com/conformal/btcutil" - ) - - func main() { - // Create a new database to store the accepted blocks into. Typically - // this would be opening an existing database and would not use memdb - // which is a memory-only database backend, but we create a new db - // here so this is a complete working example. - db, err := btcdb.CreateDB("memdb") - if err != nil { - fmt.Printf("Failed to create database: %v\n", err) - return - } - defer db.Close() - - // Insert the main network genesis block. This is part of the initial - // database setup. Like above, this typically would not be needed when - // opening an existing database. - genesisBlock := btcutil.NewBlock(btcnet.MainNetParams.GenesisBlock) - _, err = db.InsertBlock(genesisBlock) - if err != nil { - fmt.Printf("Failed to insert genesis block: %v\n", err) - return - } - - // Create a new BlockChain instance using the underlying database for - // the main bitcoin network and ignore notifications. - chain := btcchain.New(db, &btcnet.MainNetParams, nil) - - // Process a block. For this example, we are going to intentionally - // cause an error by trying to process the genesis block which already - // exists. - _, err = chain.ProcessBlock(genesisBlock, btcchain.BFNone) - if err != nil { - fmt.Printf("Failed to process block: %v\n", err) - return - } - } + - ProcessBlock Example + Demonstrates how to create a new chain instance and use ProcessBlock to + attempt to attempt add a block to the chain. This example intentionally + attempts to insert a duplicate genesis block to illustrate how an invalid + block is handled. Errors diff --git a/example_test.go b/example_test.go new file mode 100644 index 00000000..b5a0d8e1 --- /dev/null +++ b/example_test.go @@ -0,0 +1,59 @@ +// Copyright (c) 2014 Conformal Systems LLC. +// Use of this source code is governed by an ISC +// license that can be found in the LICENSE file. + +package btcchain_test + +import ( + "fmt" + "github.com/conformal/btcchain" + "github.com/conformal/btcdb" + _ "github.com/conformal/btcdb/memdb" + "github.com/conformal/btcnet" + "github.com/conformal/btcutil" +) + +// This example demonstrates how to create a new chain instance and use +// ProcessBlock to attempt to attempt add a block to the chain. As the package +// overview documentation describes, this includes all of the Bitcoin consensus +// rules. This example intentionally attempts to insert a duplicate genesis +// block to illustrate how an invalid block is handled. +func ExampleProcessBlock() { + // Create a new database to store the accepted blocks into. Typically + // this would be opening an existing database and would not use memdb + // which is a memory-only database backend, but we create a new db + // here so this is a complete working example. + db, err := btcdb.CreateDB("memdb") + if err != nil { + fmt.Printf("Failed to create database: %v\n", err) + return + } + defer db.Close() + + // Insert the main network genesis block. This is part of the initial + // database setup. Like above, this typically would not be needed when + // opening an existing database. + genesisBlock := btcutil.NewBlock(btcnet.MainNetParams.GenesisBlock) + _, err = db.InsertBlock(genesisBlock) + if err != nil { + fmt.Printf("Failed to insert genesis block: %v\n", err) + return + } + + // Create a new BlockChain instance using the underlying database for + // the main bitcoin network and ignore notifications. + chain := btcchain.New(db, &btcnet.MainNetParams, nil) + + // Process a block. For this example, we are going to intentionally + // cause an error by trying to process the genesis block which already + // exists. + isOrphan, err := chain.ProcessBlock(genesisBlock, btcchain.BFNone) + if err != nil { + fmt.Printf("Failed to process block: %v\n", err) + return + } + fmt.Println("Block accepted. Is it an orphan?: %v", isOrphan) + + // Output: + // Failed to process block: already have block 000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f +}