181 lines
4.0 KiB
Markdown
181 lines
4.0 KiB
Markdown
# HeroScript
|
|
|
|
A Go package for parsing and executing HeroScript, a small scripting language for defining actions.
|
|
|
|
## HeroScript Format
|
|
|
|
HeroScript is a simple scripting language with the following structure:
|
|
|
|
```heroscript
|
|
!!actor.action
|
|
name: 'value'
|
|
key: 'value'
|
|
numeric_value: 25
|
|
boolean_value: 1
|
|
description: '
|
|
A multiline description
|
|
can be added here.
|
|
|
|
It supports multiple paragraphs.
|
|
'
|
|
```
|
|
|
|
Key features:
|
|
- Every action starts with `!!` (for SAL actions)
|
|
- The first part is the actor (e.g., `mailclient`)
|
|
- The second part is the action name (e.g., `configure`)
|
|
- Parameters follow in an indented block
|
|
- Multiline strings are supported using single quotes
|
|
- Comments start with `//`
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
```go
|
|
import (
|
|
"fmt"
|
|
"github.com/freeflowuniverse/heroagent/pkg/heroscript/playbook"
|
|
)
|
|
|
|
// Create a new playbook from HeroScript text
|
|
script := `
|
|
!!mailclient.configure
|
|
name: 'myname'
|
|
host: 'localhost'
|
|
port: 25
|
|
secure: 1
|
|
`
|
|
|
|
pb, err := playbook.NewFromText(script)
|
|
if err != nil {
|
|
// Handle error
|
|
}
|
|
|
|
// Access actions
|
|
for _, action := range pb.Actions {
|
|
fmt.Printf("Action: %s.%s\n", action.Actor, action.Name)
|
|
|
|
// Access parameters
|
|
name := action.Params.Get("name")
|
|
host := action.Params.Get("host")
|
|
port := action.Params.GetInt("port")
|
|
secure := action.Params.GetBool("secure")
|
|
|
|
// Do something with the action...
|
|
}
|
|
```
|
|
|
|
### Finding Actions
|
|
|
|
```go
|
|
// Find all actions for a specific actor
|
|
mailActions, err := pb.FindActions(0, "mailclient", "", playbook.ActionTypeUnknown)
|
|
if err != nil {
|
|
// Handle error
|
|
}
|
|
|
|
// Find a specific action
|
|
configAction, err := pb.GetAction(0, "mailclient", "configure")
|
|
if err != nil {
|
|
// Handle error
|
|
}
|
|
```
|
|
|
|
### Generating HeroScript
|
|
|
|
```go
|
|
// Generate HeroScript from the playbook
|
|
script := pb.HeroScript(true) // true to include done actions
|
|
fmt.Println(script)
|
|
|
|
// Generate HeroScript excluding done actions
|
|
script = pb.HeroScript(false)
|
|
fmt.Println(script)
|
|
```
|
|
|
|
## Action Types
|
|
|
|
HeroScript supports different action types:
|
|
|
|
- `!action` - DAL (Data Access Layer)
|
|
- `!!action` - SAL (Service Access Layer)
|
|
- `!!!action` - Macro
|
|
|
|
## Integration with HandlerFactory
|
|
|
|
The HeroScript package can be used with the HandlerFactory to process commands. Each handler is associated with an actor and implements methods for each action it supports.
|
|
|
|
### Handler Implementation
|
|
|
|
To create a handler that works with the HandlerFactory and HeroScript:
|
|
|
|
```go
|
|
// MyHandler handles actions for the "myactor" actor
|
|
type MyHandler struct {
|
|
handlerfactory.BaseHandler
|
|
}
|
|
|
|
// NewMyHandler creates a new MyHandler
|
|
func NewMyHandler() *MyHandler {
|
|
return &MyHandler{
|
|
BaseHandler: handlerfactory.BaseHandler{
|
|
ActorName: "myactor",
|
|
},
|
|
}
|
|
}
|
|
|
|
// Play processes all actions for this handler's actor
|
|
func (h *MyHandler) Play(script string, handler interface{}) (string, error) {
|
|
return h.BaseHandler.Play(script, handler)
|
|
}
|
|
|
|
// DoSomething handles the myactor.do_something action
|
|
func (h *MyHandler) DoSomething(script string) string {
|
|
log.Printf("MyActor.DoSomething called with: %s", script)
|
|
params, err := h.ParseParams(script)
|
|
if err != nil {
|
|
return fmt.Sprintf("Error parsing parameters: %v", err)
|
|
}
|
|
|
|
// Process the action...
|
|
return "Action completed successfully"
|
|
}
|
|
```
|
|
|
|
### Using with HandlerFactory
|
|
|
|
```go
|
|
// Create a new handler factory
|
|
factory := handlerfactory.NewHandlerFactory()
|
|
|
|
// Create and register a handler
|
|
myHandler := NewMyHandler()
|
|
err := factory.RegisterHandler(myHandler)
|
|
if err != nil {
|
|
log.Fatalf("Failed to register handler: %v", err)
|
|
}
|
|
|
|
// Process a HeroScript command
|
|
result, err := factory.ProcessHeroscript(`
|
|
!!myactor.do_something
|
|
param1: 'value1'
|
|
param2: 'value2'
|
|
`)
|
|
if err != nil {
|
|
log.Fatalf("Error processing heroscript: %v", err)
|
|
}
|
|
|
|
fmt.Println(result)
|
|
```
|
|
|
|
## Example
|
|
|
|
See the [example](./example/main.go) for a complete demonstration of how to use this package.
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
go test -v ./pkg/heroscript/playbook
|
|
```
|