Merge pull request #174 from tendermint/examples-in-readme

update readme with example code

README.md

@@ -15,6 +15,15 @@ Previously, the ABCI was referred to as TMSP.
 
 The community has provided a number of addtional implementations, see the [Tendermint Ecosystem](https://tendermint.com/ecosystem)
 
+## Install
+
+```
+go get github.com/tendermint/abci
+cd $GOPATH/src/github.com/tendermint/abci
+make get_vendor_deps
+make install
+```
+
 ## Implementation
 
 We provide three implementations of the ABCI in Go:
@@ -24,19 +33,21 @@ We provide three implementations of the ABCI in Go:
 - GRPC
 
 Note the GRPC version is maintained primarily to simplify onboarding and prototyping and is not receiving the same
-attention to security and performance as the others.
+attention to security and performance as the others
 
 ### In Process
 
 The simplest implementation just uses function calls within Go.
 This means ABCI applications written in Golang can be compiled with TendermintCore and run as a single binary.
 
+See the [examples](#examples) below for more information.
+
 ### Socket (TSP)
 
 ABCI is best implemented as a streaming protocol.
 The socket implementation provides for asynchronous, ordered message passing over unix or tcp.
 Messages are serialized using Protobuf3 and length-prefixed.
-Protobuf3 doesn't have an official length-prefix standard, so we use our own.  The first byte represents the length of the big-endian encoded length.
+Protobuf3 doesn't have an official length-prefix standard, so we use our own. The first byte represents the length of the big-endian encoded length.
 
 For example, if the Protobuf3 encoded ABCI message is `0xDEADBEEF` (4 bytes), the length-prefixed message is `0x0104DEADBEEF`.  If the Protobuf3 encoded ABCI message is 65535 bytes long, the length-prefixed message would be like `0x02FFFF...`.
 
@@ -55,22 +66,82 @@ For instance, `abci-cli test` will run a test sequence against a listening serve
 It can also be used to run some example applications.
 See [the documentation](http://tendermint.readthedocs.io/en/master/) for more details.
 
-### Example Apps
+### Examples
+
+Check out the variety of example applications in the [example directory](example/).
+It also contains the code refered to by the `counter` and `dummy` apps; these apps come
+built into the `abci-cli` binary.
 
-Multiple example apps are included:
-- the `abci-cli counter` application, which illustrates nonce checking in txs
-- the `abci-cli dummy` application, which illustrates a simple key-value Merkle tree
-- the `abci-cli dummy --persistent` application, which augments the dummy with persistence and validator set changes
+#### Counter
 
-### Install
+The `abci-cli counter` application illustrates nonce checking in transactions. It's code looks like:
 
+```golang
+func cmdCounter(cmd *cobra.Command, args []string) error {
+
+	app := counter.NewCounterApplication(flagSerial)
+
+	logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout))
+
+	// Start the listener
+	srv, err := server.NewServer(flagAddrC, flagAbci, app)
+	if err != nil {
+		return err
+	}
+	srv.SetLogger(logger.With("module", "abci-server"))
+	if err := srv.Start(); err != nil {
+		return err
+	}
+
+	// Wait forever
+	cmn.TrapSignal(func() {
+		// Cleanup
+		srv.Stop()
+	})
+	return nil
+}
 ```
-go get github.com/tendermint/abci
-cd $GOPATH/src/github.com/tendermint/abci
-make get_vendor_deps
-make install
+
+and can be found in [this file](cmd/abci-cli/abci-cli.go).
+
+#### Dummy
+
+The `abci-cli dummy` application, which illustrates a simple key-value Merkle tree
+
+```golang
+func cmdDummy(cmd *cobra.Command, args []string) error {
+	logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout))
+
+	// Create the application - in memory or persisted to disk
+	var app types.Application
+	if flagPersist == "" {
+		app = dummy.NewDummyApplication()
+	} else {
+		app = dummy.NewPersistentDummyApplication(flagPersist)
+		app.(*dummy.PersistentDummyApplication).SetLogger(logger.With("module", "dummy"))
+	}
+
+	// Start the listener
+	srv, err := server.NewServer(flagAddrD, flagAbci, app)
+	if err != nil {
+		return err
+	}
+	srv.SetLogger(logger.With("module", "abci-server"))
+	if err := srv.Start(); err != nil {
+		return err
+	}
+
+	// Wait forever
+	cmn.TrapSignal(func() {
+		// Cleanup
+		srv.Stop()
+	})
+	return nil
+}
 ```
 
+and can be found in [this file](cmd/abci-cli/abci-cli.go).
+
 ## Specification
 
 See the [spec file](specification.rst) for more information.

cmd/abci-cli/abci-cli.go

@@ -327,8 +327,10 @@ func cmdTest(cmd *cobra.Command, args []string) error {
 			func() error { return servertest.DeliverTx(client, []byte{0x00, 0x02}, code.CodeTypeOK, nil) },
 			func() error { return servertest.DeliverTx(client, []byte{0x00, 0x03}, code.CodeTypeOK, nil) },
 			func() error { return servertest.DeliverTx(client, []byte{0x00, 0x00, 0x04}, code.CodeTypeOK, nil) },
-			func() error { return servertest.DeliverTx(client, []byte{0x00, 0x00, 0x06}, code.CodeTypeBadNonce, nil) },
-			func() error { return servertest.Commit(client, []byte{0, 0, 0, 0, 0, 0, 0, 5})},
+			func() error {
+				return servertest.DeliverTx(client, []byte{0x00, 0x00, 0x06}, code.CodeTypeBadNonce, nil)
+			},
+			func() error { return servertest.Commit(client, []byte{0, 0, 0, 0, 0, 0, 0, 5}) },
 		})
 }