Break

CHANGES.md

@@ -1,3 +1,8 @@
+### v0.9.0
+
+ - adds Break(key,value,...) for temporary runtime inspection. 
+ - add optional filename to Dump()
+
 ### v0.8.1
 
  - Explore replaces object with same root label.

README.md

@@ -49,6 +49,14 @@ Note: if the list contains just one structural value then selecting it can be sk
 
 ## explore while debugging
 
+### Break
+
+The following instruction will start the explorer on a struct, opens a Browser and provides a `resume` button to stop the explorer and resume the Go-routine that started it.
+
+    structexplorer.Break("myStruct", myStruct)
+
+### Dump
+
 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.
 
@@ -57,10 +65,14 @@ The explorer can also be asked to dump an HTML page with the current state of va
     s := structexplorer.NewService()
     s.Explore("yours", yourStruct)
     s.ExplorePath("yours.field") // dotted path of fields starting with an explore label
-    s.Dump()
+    s.Dump() 
+    // or s.Dump("yourfile.html")
 
 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.
+
+
+© 2025. https://ernestmicklei.com. MIT License

examples/break/main.go

@@ -0,0 +1,20 @@
+package main
+
+import (
+	"log"
+
+	"github.com/emicklei/structexplorer"
+)
+
+// go run .
+func main() {
+	greeting := map[string]any{}
+	hello := struct{ Field string }{Field: "hello"}
+	greeting["hi"] = hello
+
+	log.Println("before opening the explorer to see state")
+
+	structexplorer.Break("map", greeting)
+
+	log.Println("after opening the explorer to see state")
+}

examples/break/main_test.go

@@ -0,0 +1,18 @@
+package main
+
+import (
+	"log"
+	"testing"
+
+	"github.com/emicklei/structexplorer"
+)
+
+func TestWithBreak(t *testing.T) {
+	target := struct{ Field string }{Field: "hello"}
+
+	log.Println("before opening the explorer to see state")
+
+	structexplorer.Break("debugging", target)
+
+	log.Println("after opening the explorer to see state")
+}

explorer.go

@@ -164,6 +164,9 @@ func (e *explorer) putObjectStartingAt(row, col int, access objectAccess, option
 }
 
 func (e *explorer) buildIndexData(b *indexDataBuilder) indexData {
+	// was it starting using Break?
+	b.data.IsBreaking = b.isBreaking
+
 	for row, each := range e.accessMap {
 		for col, access := range each {
 			info := b.build(row, col, access)

index_builder.go

@@ -10,10 +10,11 @@ import (
 )
 
 type indexDataBuilder struct {
-	data     indexData
-	seq      int
-	notLive  bool
-	selectID string // id of the added fieldList (select element)
+	data       indexData
+	seq        int
+	notLive    bool
+	isBreaking bool   // service is started with Break(...)
+	selectID   string // id of the added fieldList (select element)
 }
 
 func newIndexDataBuilder() *indexDataBuilder {

index_data.go

@@ -14,9 +14,10 @@ var styleCSS string
 
 type (
 	indexData struct {
-		Rows   []tableRow
-		Script template.JS
-		Style  template.CSS
+		Rows       []tableRow
+		Script     template.JS
+		Style      template.CSS
+		IsBreaking bool
 	}
 	tableRow struct {
 		Cells []fieldList

index_tmpl.html

@@ -121,6 +121,11 @@
             <span id="theme-toggle" class="theme-toggle" title="Toggle Theme"
                 >🔄</span
             >
+            {{- if .IsBreaking }}
+            <button class="btn" title="resume from a break" onclick="javascript:resume();">
+                Resume from Breakpoint
+            </button>        
+            {{- end }}
         </p>
 
         <script>

open.go

@@ -0,0 +1,21 @@
+package structexplorer
+
+import (
+	"fmt"
+	"os/exec"
+	"runtime"
+)
+
+// Open calls the OS default program for uri
+func open(uri string) error {
+	switch {
+	case "windows" == runtime.GOOS:
+		return exec.Command("rundll32", "url.dll,FileProtocolHandler", uri).Start()
+	case "darwin" == runtime.GOOS:
+		return exec.Command("open", uri).Start()
+	case "linux" == runtime.GOOS:
+		return exec.Command("xdg-open", uri).Start()
+	default:
+		return fmt.Errorf("unable to open uri:%v on:%v", uri, runtime.GOOS)
+	}
+}

script.js

@@ -13,8 +13,18 @@ function explore(row, column, selectNode, action) {
         action: action,
         selections: getSelectValues(selectNode)
     }));
-    xhr.onload = function () { window.location.reload(); }
+    xhr.onload = function() { window.location.reload(); }
 }
+
+function resume() {
+    const xhr = new XMLHttpRequest();
+    xhr.open("POST", window.location.href);
+    xhr.setRequestHeader("Content-Type", "application/json; charset=UTF-8")
+    xhr.send(JSON.stringify({
+        action: "resume" 
+    }));
+}
+
 // Return an array of the selected option values in the control.
 // Select is an HTML select element.
 function getSelectValues(select) {
@@ -34,4 +44,4 @@ function getSelectValues(select) {
         result.push(opt.value || opt.text);
     }
     return result;
-}
+} 

service.go

@@ -1,6 +1,7 @@
 package structexplorer
 
 import (
+	"context"
 	_ "embed"
 	"encoding/json"
 	"fmt"
@@ -18,8 +19,11 @@ type Service interface {
 	// Start accepts 0 or 1 Options
 	Start(opts ...Options)
 
+	// Break accepts 0 or 1 Options
+	Break(opts ...Options)
+
 	// Dump writes an HTML file for displaying the current state of the explorer and its entries.
-	Dump()
+	Dump(optionFilename ...string)
 
 	// Explore adds or replaces (matching on label) a new entry for a value unless it cannot be explored.
 	// The object will be placed on the next available column on row 1.
@@ -44,6 +48,7 @@ func (s *service) init() {
 type service struct {
 	explorer      *explorer
 	indexTemplate *template.Template
+	httpServer    *http.Server
 }
 
 // NewService creates a new to explore one or more values (structures).
@@ -53,6 +58,45 @@ func NewService(labelValuePairs ...any) Service {
 	return s
 }
 
+// Break will listen and serve on the default endpoint and opens a window.
+// The explorer page will have a button "Resume" that stops the server
+// and unblocks the go-routine that started it.
+func Break(keyvaluePairs ...any) {
+	NewService(keyvaluePairs...).Break(Options{
+		ServeMux: new(http.ServeMux),
+	})
+}
+
+// Break will listen and serve on the given http port and path.
+// it accepts 0 or 1 Options to override defaults.
+// The opened explorer page will have a button "Resume" that stops the server
+// and unblocks the go-routine that started it.
+func (s *service) Break(opts ...Options) {
+	if len(opts) > 0 {
+		s.explorer.options = &opts[0]
+	}
+	port := s.explorer.options.httpPort()
+	serveMux := s.explorer.options.serveMux()
+	rootPath := s.explorer.options.rootPath()
+	serveMux.Handle(rootPath, s)
+	server := &http.Server{
+		Addr:    fmt.Sprintf(":%d", port),
+		Handler: serveMux,
+	}
+	s.httpServer = server
+	open(fmt.Sprintf("http://localhost:%d", port))
+	// this blocks until server is closed by resume operation.
+	server.ListenAndServe()
+}
+
+func (s *service) resume() {
+	if s.httpServer == nil {
+		return
+	}
+	s.httpServer.Shutdown(context.Background())
+	s.httpServer = nil
+}
+
 // Start will listen and serve on the given http port and path.
 // it accepts 0 or 1 Options to override defaults.
 func (s *service) Start(opts ...Options) {
@@ -64,7 +108,7 @@ func (s *service) Start(opts ...Options) {
 	rootPath := s.explorer.options.rootPath()
 	slog.Info(fmt.Sprintf("starting go struct explorer at http://localhost:%d%s on %v", port, rootPath, s.explorer.rootKeys()))
 	serveMux.Handle(rootPath, s)
-	if err := http.ListenAndServe(fmt.Sprintf(":%d", port), nil); err != nil {
+	if err := http.ListenAndServe(fmt.Sprintf(":%d", port), serveMux); err != nil {
 		slog.Error("[structexplorer] failed to start service", "err", err)
 	}
 }
@@ -98,7 +142,11 @@ func (s *service) serveIndex(w http.ResponseWriter, _ *http.Request) {
 	defer s.protect()()
 
 	w.Header().Set("content-type", "text/html")
-	if err := s.indexTemplate.Execute(w, s.explorer.buildIndexData(newIndexDataBuilder())); err != nil {
+
+	builder := newIndexDataBuilder()
+	builder.isBreaking = s.httpServer != nil
+
+	if err := s.indexTemplate.Execute(w, s.explorer.buildIndexData(builder)); err != nil {
 		slog.Error("failed to execute template", "err", err)
 		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
@@ -142,10 +190,14 @@ func (s *service) Explore(label string, value any, options ...ExploreOption) Ser
 }
 
 // Dump writes an HTML file for displaying the current state of the explorer and its entries.
-func (s *service) Dump() {
+func (s *service) Dump(optionalFilename ...string) {
 	defer s.protect()()
 
-	out, err := os.Create("structexplorer.html")
+	fName := "structexplorer.html"
+	if len(optionalFilename) > 0 && optionalFilename[0] != "" {
+		fName = optionalFilename[0]
+	}
+	out, err := os.Create(fName)
 	if err != nil {
 		slog.Error("failed to create dump file", "err", err)
 	}
@@ -204,6 +256,10 @@ func (s *service) serveInstructions(w http.ResponseWriter, r *http.Request) {
 	case "clear":
 		s.explorer.removeNonRootObjects()
 		return
+	case "resume":
+		s.resume()
+		return
+
 	default:
 		slog.Warn("[structexplorer] invalid direction", "action", cmd.Action)
 		http.Error(w, "invalid action", http.StatusBadRequest)