Feature/code primitive (#133)

* Added initial documentation for `code` primitive

* Initial code primitive

* Fixed unit tests

---------

Co-authored-by: Jaakko Heusala <jhh@hg.fi>

Author: thejhh

cmd/gnd/main.go

@@ -3,10 +3,11 @@ package main
 import (
 	"flag"
 	"fmt"
-	"github.com/hyperifyio/gnd/pkg/primitive"
 	"os"
 	"path/filepath"
 
+	"github.com/hyperifyio/gnd/pkg/primitive"
+
 	"github.com/hyperifyio/gnd/pkg/core"
 	"github.com/hyperifyio/gnd/pkg/log"
 	"github.com/hyperifyio/gnd/pkg/parsers"
@@ -31,6 +32,7 @@ var DefaultOpcodeMap = map[string]string{
 	"debug":     "/gnd/debug",
 	"exit":      "/gnd/exit",
 	"return":    "/gnd/return",
+	"code":      "/gnd/code",
 }
 
 func printHelp() {

docs/code-syntax.md

@@ -0,0 +1,72 @@
+The `code` operation produces an instruction array that Gendo can treat as 
+ordinary data. Called with no arguments, it yields the instruction array of the 
+routine that is currently executing. Called with one or more targets, it 
+resolves each target's instructions in left-to-right order and returns a single 
+array containing all of them, without altering the originals.
+
+The syntax of the `code` operation is:
+
+```
+[ $destination ] code [ target1 target2 ... ]
+```
+
+The `$destination` is optional. If omitted, the result is assigned to the 
+special slot `_`. When **no** target is supplied, the current routine's 
+instructions are returned. When **one or more** targets are supplied, each 
+target must be one of:
+
+* `@` - represents the current routine's instructions
+* a string literal ending in `.gnd` – the file is loaded (and compiled if necessary);
+* an opcode identifier – returns a one-instruction array for that primitive;
+* a `$variable` already bound to a routine value.
+
+Targets are resolved independently; the final result is a new instruction array 
+consisting of the instructions from `target1`, followed by those of `target2`, 
+and so on.
+
+Examples
+
+Return the current routine's code, compile it, and run in parallel:
+
+```
+$compiled compile "debug hello world"       # compile our own instructions
+$task     async   $compiled  # run in background
+await _   $task              # wait and get result
+```
+
+Merge two external files and execute once:
+
+```
+$math   code math
+$string code string
+$all    code $math $string   # concatenate in this order
+_exec   exec $all
+```
+
+Combine a primitive with a helper routine and inspect length:
+
+```
+$addOp  code add
+$utils  code helpers
+$merged code $addOp $utils
+$count  len  $merged
+```
+
+Combine current routine with a helper routine:
+
+```
+$current code @              # get current routine's instructions
+$utils   code helpers        # get helper routine's instructions
+$merged  code @ $utils       # combine current routine with helpers
+$count   len  $merged        # get total instruction count
+```
+
+Errors
+
+* If any file target cannot be loaded or compiled, `code` raises an error.
+* If a variable target is unbound or not a routine value, an error is raised.
+* The operation never mutates its inputs; it always returns a fresh instruction array.
+
+The returned array is immutable and can be stored, passed, compiled, or 
+executed by other operations such as `compile`, `exec`, `async`, or further 
+`code` concatenations.

examples/code-example.gnd

@@ -0,0 +1 @@
+code normalize

examples/llm.gnd

@@ -1,6 +1,5 @@
 $args let
 debug "Our input is:" $args
-return "This is test"
 $persona let "You are a helpful assistant.\n---\n"
 $instruction let "\n---\nIs the previous input acceptable? Reply 'true' or 'false'."
 $fullPrompt concat $persona $args $instruction

pkg/core/interpreter.go

@@ -28,4 +28,7 @@ type Interpreter interface {
 
 	// GetSlot gets a slot value
 	GetSlot(name string) (interface{}, error)
+
+	// GetSubroutineInstructions retrieves the instructions for a subroutine
+	GetSubroutineInstructions(path string) ([]*parsers.Instruction, error)
 }

pkg/core/interpreter_impl.go

@@ -142,15 +142,31 @@ func (i *InterpreterImpl) ExecuteInstructionBlock(source string, input interface
 	lastResult := input
 	for idx, op := range instructions {
 		if op != nil {
+
 			i.LogDebug("[%s:%d]: ExecuteInstructionBlock: %v <- %s %v", source, idx, op.Destination, op.Opcode, op.Arguments)
+
 			result, err := i.ExecuteInstruction(op.Opcode, op.Destination, op.Arguments)
+
 			if err != nil {
 				if returnValue, ok := primitive.GetReturnValue(err); ok {
 					i.LogDebug("[%s:%d]: ExecuteInstructionBlock: return by ReturnValue: %v", source, idx, returnValue.Value)
 					return returnValue.Value, nil
 				}
 				return nil, fmt.Errorf("\n  %s:%d: %v", source, idx, err)
 			}
+
+			if codeResult, ok := primitive.GetCodeResult(result); ok {
+				codeInstructions, err := i.HandleCodeResult(source, codeResult, instructions)
+				if err != nil {
+					return nil, err
+				}
+
+				// Store the codeInstructions in the destination slot
+				i.LogDebug("[%s]: ExecutePrimitive: storing %d codeInstructions in %s", source, len(codeInstructions), op.Destination.Name)
+				i.Slots[op.Destination.Name] = codeInstructions
+				return codeInstructions, nil
+			}
+
 			lastResult = result
 		}
 	}
@@ -257,13 +273,74 @@ func (i *InterpreterImpl) LoadArguments(source string, arguments []interface{})
 	return resolvedArgs, nil
 }
 
+// HandleCodeResult processes a CodeResult and returns the concatenated instructions
+func (i *InterpreterImpl) HandleCodeResult(source string, codeResult *primitive.CodeResult, block []*parsers.Instruction) ([]*parsers.Instruction, error) {
+	i.LogDebug("[%s]: HandleCodeResult: processing targets: %v", source, codeResult.Targets)
+	var allInstructions []*parsers.Instruction
+
+	// Process each target in order
+	for _, target := range codeResult.Targets {
+		var instructions []*parsers.Instruction
+
+		switch v := target.(type) {
+		case string:
+			if v == "@" {
+				if block == nil {
+					return nil, fmt.Errorf("[%s]: HandleCodeResult: no instructions provided for @", source)
+				}
+				instructions = append(instructions, block...)
+			} else {
+
+				// Get instructions using existing subroutine logic
+				pwd := i.GetScriptDir()
+				i.LogDebug("[%s]: HandleCodeResult: pwd = %s", source, pwd)
+
+				// Check if the subroutine is already loaded
+				subPath := SubroutinePath(v, pwd)
+				i.LogDebug("[%s]: HandleCodeResult: subPath = %v", source, subPath)
+
+				var err error
+				instructions, err = i.GetSubroutineInstructions(subPath)
+				i.LogDebug("[%s]: HandleCodeResult: instructions = %v", source, instructions)
+				if err != nil {
+					return nil, fmt.Errorf("[%s]: HandleCodeResult: failed to get instructions for %v: %v", source, target, err)
+				}
+				if instructions == nil {
+					return nil, fmt.Errorf("[%s]: HandleCodeResult: no instructions found for %v", source, target)
+				}
+
+			}
+		case []*parsers.Instruction:
+			// Use the instructions directly
+			instructions = v
+			if instructions == nil {
+				return nil, fmt.Errorf("[%s]: HandleCodeResult: no instructions found for %v", source, target)
+			}
+		case *parsers.Instruction:
+			// Use the instructions directly
+			instructions = []*parsers.Instruction{v}
+			if instructions == nil {
+				return nil, fmt.Errorf("[%s]: HandleCodeResult: no instructions found for %v", source, target)
+			}
+		default:
+			return nil, fmt.Errorf("[%s]: HandleCodeResult: invalid target type: %T", source, target)
+		}
+
+		// Append instructions to the result
+		allInstructions = append(allInstructions, instructions...)
+	}
+
+	return allInstructions, nil
+}
+
 // ExecutePrimitive executes a single GND primitive and returns its result
 func (i *InterpreterImpl) ExecutePrimitive(prim primitive.Primitive, destination *parsers.PropertyRef, arguments []interface{}) (interface{}, error) {
 
 	// Log regular instruction
 	i.LogDebug("[%s]: ExecutePrimitive: %v <- %s %v", prim.Name(), destination, prim.Name(), arguments)
 
 	result, err := prim.Execute(arguments)
+
 	if err != nil {
 
 		// Check if this is a ReturnValue
@@ -289,6 +366,12 @@ func (i *InterpreterImpl) ExecutePrimitive(prim primitive.Primitive, destination
 		return nil, fmt.Errorf("[%s]: ExecutePrimitive: error: %v", prim.Name(), err)
 	}
 
+	// Check if this is a CodeResult
+	if codeResult, ok := primitive.GetCodeResult(result); ok {
+		i.LogDebug("[%s]: ExecutePrimitive: code result detected: %v", prim.Name(), codeResult)
+		return codeResult, nil
+	}
+
 	// Store the result in the destination slot
 	i.LogDebug("[%s]: ExecutePrimitive: %v <- %v", prim.Name(), destination, log.StringifyValue(result))
 	i.Slots[destination.Name] = result