structexplorer

README

structexplorer

A Go Struct Explorer Service (http.Handler) that offers remote inspection of any Go struct and its references.

example of exploring a yaegi program

install

go get github.com/emicklei/structexplorer

usage

structexplorer.NewService("some structure", yourStruct).Start()

then a HTTP service will be started

INFO starting go struct explorer at http://localhost:5656

or as root HTTP Handler:

s := structexplorer.NewService("some structure", yourStruct, "other" , otherStruct)
http.ListenAndServe(":5656", s)

or as a HTTP Handler function:

http.HandleFunc("/explore", structexplorer.NewService("game", game).ServeHTTP)

syntax

• if a value is a pointer to a standard type then the display value has a "*" prefix
• if a value is a reflect.Value then the display value has a "~" prefix

buttons

• ⇊ : explore one or more selected values from the list and put them on the row below
• ⇉ : explore one or more selected values from the list and put them on the right
• ⇈ : explore one or more selected values from the list and put them on the row up
• z : show or hide fields which currently have zero value ("",0,nil,false)
• x : remove the struct from the page
• c : remove all struct from the page except the onces you started with

Note: if the list contains just one structural value then selecting it can be skipped for ⇊, ⇈ and ⇉.

explore while debugging

Currently, the standard Go debugger delve stops all goroutines while in a debugging session. This means that if you have started the structexplorer service in your program, it will not respond to any HTTP requests during that session.

The explorer can also be asked to dump an HTML page with the current state of values to a file.

s := structexplorer.NewService()
s.Explore("yours", yourStruct)
s.ExplorePath("yours.field") // dotted path of fields starting with an explore label
s.Dump()

Another method is to use a special test case which starts an explorer at the end of a test and then run it with a longer acceptable timeout.

examples

See folder examples for simple programs demonstrating each feature.

Documentation

Index

• type ExploreOption
  • func Column(column int) ExploreOption
  • func Row(row int) ExploreOption
  • func RowColumn(row, column int) ExploreOption
• type Options
• type Service
  • func NewService(labelValuePairs ...any) Service

Types

type ExploreOption

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

ExploreOption is a type for the options that can be passed to the Explore or Follow function.

func Column

func Column(column int) ExploreOption

Column places the next object in the same column on a new free row.

func Row

func Row(row int) ExploreOption

Row places the next object in the same row on a new free column.

func RowColumn

func RowColumn(row, column int) ExploreOption

RowColumn places the next object in the specified row and column.

type Options

type Options struct {
	// Uses 5656 as the default
	HTTPPort int
	// Uses http.DefaultServeMux as default
	ServeMux *http.ServeMux
	// Uses "/" as default
	HTTPBasePath string
}

Options can be used to configure a Service on startup.

type Service

type Service interface {
	http.Handler
	// Start accepts 0 or 1 Options
	Start(opts ...Options)

	// Dump writes an HTML file for displaying the current state of the explorer and its entries.
	Dump()

	// Explore adds a new entry (next available row in column 0) for a value unless it cannot be explored.
	Explore(label string, value any, options ...ExploreOption) Service

	// ExplorePath adds a new entry for a value at the specified access path unless it cannot be explored.
	ExplorePath(dottedPath string, options ...ExploreOption) Service
}

Service is an HTTP Handler to explore one or more values (structures).

func NewService

func NewService(labelValuePairs ...any) Service

NewService creates a new to explore one or more values (structures).