Use testable example and update doc.go README.md.

This commit adds an example 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 included in README.md in
place of the example.

README.md

@@ -23,15 +23,6 @@ the bitcoin transactions.  This language is not turing complete
 although it is still fairly powerful.  A description of the language
 can be found at https://en.bitcoin.it/wiki/Script
 
-## Sample Use
-
-```Go
-	pkscript := txS.TxOut[origintxidx].PkScript
-	engine, err := btcscript.NewScript(sigScript, pkscript, txInIdx,
-		txValidator, timestamp.After(btcscript.Bip16Activation))
-	err = engine.Execute()
-```
-
 ## Documentation
 
 [![GoDoc](https://godoc.org/github.com/conformal/btcscript?status.png)]
@@ -51,6 +42,14 @@ http://localhost:6060/pkg/github.com/conformal/btcscript
 $ go get github.com/conformal/btcscript
 ```
 
+## Examples
+
+* [Standard Pay-to-pubkey-hash Script]
+  (http://godoc.org/github.com/conformal/btcdb#example-PayToAddrScript)  
+  Demonstrates creating a script which pays to a bitcoin address.  It also
+  prints the created script hex and uses the DisasmString function to display
+  the disassembled script.
+
 ## TODO
 
 - Increase test coverage to 100%

doc.go

@@ -30,29 +30,6 @@ is used to prove the the spender is authorized to perform the transaction.
 One benefit of using a scripting language is added flexibility in specifying
 what conditions must be met in order to spend bitcoins.
 
-Usage
-
-The usage of this package consists of creating a new script engine for a pair
-of transaction inputs and outputs and using the engine to execute the scripts.
-
-The following function is an example of how to create and execute a script
-engine to validate a transaction.
-
-	// ValidateTx validates the txIdx'th input of tx. The output transaction
-	// corresponding to the this input is the txInIdx'th output of txIn. The
-	// block timestamp of tx is timestamp.
-	func ValidateTx(tx *btcwire.MsgTx, txIdx int, txIn *btcwire.MsgTx, txInIdx int, timestamp time.Time) {
-		pkScript := txIn.TxOut[txInIdx].PkScript
-		sigScript := tx.txIn[TxIdx]
-		var flags btcscript.ScriptFlags
-		if timestamp.After(btcscript.Bip16Activation) {
-			flags |= btcscript.ScriptBip16
-		}
-		engine, err := btcscript.NewScript(sigScript, pkScript, txInIdx,
-			tx, flags)
-		return engine.Execute()
-	}
-
 Errors
 
 Errors returned by this package are of the form btcscript.StackErrX where X

example_test.go

@@ -0,0 +1,48 @@
+// 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 btcscript_test
+
+import (
+	"fmt"
+
+	"github.com/conformal/btcnet"
+	"github.com/conformal/btcscript"
+	"github.com/conformal/btcutil"
+)
+
+// This example demonstrates creating a script which pays to a bitcoin address.
+// It also prints the created script hex and uses the DisasmString function to
+// display the disassembled script.
+func ExamplePayToAddrScript() {
+	// Parse the address to send the coins to into a btcutil.Address
+	// which is useful to ensure the accuracy of the address and determine
+	// the address type.  It is also required for the upcoming call to
+	// PayToAddrScript.
+	addressStr := "12gpXQVcCL2qhTNQgyLVdCFG2Qs2px98nV"
+	address, err := btcutil.DecodeAddress(addressStr, &btcnet.MainNetParams)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+
+	// Create a public key script that pays to the address.
+	script, err := btcscript.PayToAddrScript(address)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Printf("Script Hex: %x\n", script)
+
+	disasm, err := btcscript.DisasmString(script)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println("Script Disassembly:", disasm)
+
+	// Output:
+	// Script Hex: 76a914128004ff2fcaf13b2b91eb654b1dc2b674f7ec6188ac
+	// Script Disassembly: OP_DUP OP_HASH160 128004ff2fcaf13b2b91eb654b1dc2b674f7ec61 OP_EQUALVERIFY OP_CHECKSIG
+}