hopwatch

README

Hopwatch, a debugging tool for Go

Hopwatch is a simple tool in HTML5 that can help debug Go programs. It works by communicating to a WebSockets based client in Javascript. When your program calls the Break function, it sends debug information to the browser page and waits for user interaction. Using the functions Display, Printf or Dump (go-spew), you can log information on the browser page. On the hopwatch page, the developer can view debug information and choose to resume the execution of the program.

Documentation on godoc.org

© 2012-2014, http://ernestmicklei.com. MIT License

Documentation

Overview

Hopwatch is a debugging tool for Go programs.

Hopwatch uses a (embedded) HTML5 application to connect to your program (using a Websocket). Using Hopwatch requires adding function calls at points of interest that allow you to watch program state and suspend the program. On the Hopwatch page, you can view debug information (file:line,stack) and choose to resume the execution of your program.

You can provide more debug information using the Display and Dump functions which take an arbitrary number of variables. The Display and Dump functions do not suspend the program ; it is like having logging information in the browser.

Usage:

import (
	// use a tag
	"gopkg.in/emicklei/hopwatch.v1"

	// or use the master
	// "github.com/emicklei/hopwatch"
)

func foo() {
	bar := "john"
	// suspends execution until hitting "Resume" in the browser
	hopwatch.Display("foo", bar).Break()
}

Connect:

The Hopwatch debugger is automatically started on http://localhost:23456/hopwatch.html.
Your browser must support WebSockets. It has been tested with Chrome and Safari on a Mac.

Other code examples:

// zero or more conditions ; conditionally suspends program (or goroutine)
hopwatch.Break(i > 10,  j < 100)

// zero or more name,value pairs ; no program suspend
hopwatch.Display("i",i , "j",j")

// print any formatted string ; no program suspend
hopwatch.Printf("result=%v", result)

// display detailed (type, nesting) information using https://github.com/davecgh/go-spew
hopwatch.Dump(myVar1)

// format and display detailed (type, nesting) information using https://github.com/davecgh/go-spew
hopwatch.Dumpf("myVar1: %v -- myVar2: %+v", myVar1, myVar2)

Flags:

-hopwatch	if set to false then hopwatch is disabled.
-hopwatch.open	if set to false then hopwatch will not try to open the debugger page on startup.
-hopwatch.break	if set to false then hopwatch will not suspend the program when Break(..) is called.
-hopwatch.host	tcp hostname of the listener address (default = localhost).
-hopwatch.port	tcp port of the listener address (default = 23456).

Install from master:

go get -u github.com/emicklei/hopwatch

or from a tag:

go get gopkg.in/emicklei/hopwatch.v1

Resources:

https://github.com/emicklei/hopwatch (project)
http://ernestmicklei.com/2012/12/14/hopwatch-a-debugging-tool-for-go/  (blog)

(c) 2012-2014, Ernest Micklei. MIT License

Index

• func Break(conditions ...bool)
• func Disable()
• func Enable()
• type Watchpoint
  • func CallerOffset(offset int) *Watchpoint
  • func Display(nameValuePairs ...interface{}) *Watchpoint
  • func Dump(a ...interface{}) *Watchpoint
  • func Dumpf(format string, a ...interface{}) *Watchpoint
  • func Printf(format string, params ...interface{}) *Watchpoint
  • func (self Watchpoint) Break(conditions ...bool)
  • func (w *Watchpoint) CallerOffset(offset int) *Watchpoint
  • func (self *Watchpoint) Display(nameValuePairs ...interface{}) *Watchpoint
  • func (w *Watchpoint) Dump(a ...interface{}) *Watchpoint
  • func (w *Watchpoint) Dumpf(format string, a ...interface{}) *Watchpoint
  • func (self *Watchpoint) Printf(format string, params ...interface{}) *Watchpoint

Functions

func Break

func Break(conditions ...bool)

Break suspends the execution of the program and waits for an instruction from the debugger (e.g. Resume). Break is only effective if all (if any) conditions are true. The program will resume otherwise.

func Disable

func Disable()

func Enable

func Enable()

Types

type Watchpoint

type Watchpoint struct {
	// contains filtered or unexported fields
}

watchpoint is a helper to provide a fluent style api. This allows for statements like hopwatch.Display("var",value).Break()

func CallerOffset

func CallerOffset(offset int) *Watchpoint

CallerOffset (default=2) allows you to change the file indicator in hopwatch. Use this method when you wrap the .CallerOffset(..).Display(..).Break() in your own function.

func Display

func Display(nameValuePairs ...interface{}) *Watchpoint

Display sends variable name,value pairs to the debugger. The parameter nameValuePairs must be even sized.

func Dump

func Dump(a ...interface{}) *Watchpoint

Dump displays the passed parameters with newlines and additional debug information such as complete types and all pointer addresses used to indirect to the final value. Delegates to spew.Fdump, see http://godoc.org/github.com/davecgh/go-spew/spew#Dump

func Dumpf

func Dumpf(format string, a ...interface{}) *Watchpoint

Dumpf formats and displays the passed parameters with newlines and additional debug information such as complete types and all pointer addresses used to indirect to the final value. delegates to spew.Fprintf, see http://godoc.org/github.com/davecgh/go-spew/spew#Dump

func Printf

func Printf(format string, params ...interface{}) *Watchpoint

Printf formats according to a format specifier and writes to the debugger screen. It returns a new Watchpoint to send more or break.

func (Watchpoint) Break

func (self Watchpoint) Break(conditions ...bool)

Break halts the execution of the program and waits for an instruction from the debugger (e.g. Resume). Break is only effective if all (if any) conditions are true. The program will resume otherwise.

func (*Watchpoint) CallerOffset

func (w *Watchpoint) CallerOffset(offset int) *Watchpoint

CallerOffset (default=2) allows you to change the file indicator in hopwatch.

func (*Watchpoint) Display

func (self *Watchpoint) Display(nameValuePairs ...interface{}) *Watchpoint

Display sends variable name,value pairs to the debugger. Values are formatted using %#v. The parameter nameValuePairs must be even sized.

func (*Watchpoint) Dump

func (w *Watchpoint) Dump(a ...interface{}) *Watchpoint

Dump displays the passed parameters with newlines and additional debug information such as complete types and all pointer addresses used to indirect to the final value. Delegates to spew.Fdump, see http://godoc.org/github.com/davecgh/go-spew/spew#Dump

func (*Watchpoint) Dumpf

func (w *Watchpoint) Dumpf(format string, a ...interface{}) *Watchpoint

Dumpf formats and displays the passed parameters with newlines and additional debug information such as complete types and all pointer addresses used to indirect to the final value. Delegates to spew.Fprintf, see http://godoc.org/github.com/davecgh/go-spew/spew#Dump

func (*Watchpoint) Printf

func (self *Watchpoint) Printf(format string, params ...interface{}) *Watchpoint

Printf formats according to a format specifier and writes to the debugger screen.