pipelinesyntax

Documentation

Overview

Package pipelinesyntax parses Jenkins' per-build pipeline-syntax endpoints (`<build>/pipeline-syntax/gdsl` and `<build>/pipeline-syntax/globals`) into a structured Symbols set the TUI can drive completion, syntax highlighting, and signature popups from.

The set is build-scoped on purpose: Jenkins evaluates @Library at build time, so the symbols exposed here already reflect the exact shared-library version that ran for this build. No git access or @Library parsing on our side.

Index

• Variables
• func LoadUserGDSLDir(dir string) (map[string][]Member, error)
• func ParseGDSL(src string) (steps []Step, globals []GlobalVar)
• func ParseUserGDSL(src string) map[string][]Member
• type GlobalVar
  • func ParseGlobals(htmlSrc string) []GlobalVar
• type Member
• type Param
• type Step
  • func (s Step) Signature() string
• type Symbols

Variables

var DefaultDSLKeywords = []string{
	"pipeline", "agent", "stages", "stage", "steps", "post",
	"when", "environment", "options", "parameters", "triggers",
	"tools", "input", "parallel", "matrix", "script", "library",
	"always", "success", "failure", "unstable", "aborted", "cleanup",
	"changed", "fixed", "regression", "unsuccessful", "any", "none",
	"label", "docker", "dockerfile", "kubernetes", "node",
}

DefaultDSLKeywords are the declarative Pipeline DSL block names. They are part of the Pipeline grammar itself rather than steps, so they don't show up in gdsl/globals — we hard-code them. Safe and stable across versions.

Functions

func LoadUserGDSLDir

func LoadUserGDSLDir(dir string) (map[string][]Member, error)

LoadUserGDSLDir walks dir (non-recursive), parses every *.gdsl file inside, and merges them into a single receiver-to-members map. Missing dir → nil result + nil error, so a fresh install just produces no extras.

func ParseGDSL

func ParseGDSL(src string) (steps []Step, globals []GlobalVar)

ParseGDSL extracts steps and properties from a raw gdsl document. Properties are surfaced as Globals (no signature).

func ParseUserGDSL

func ParseUserGDSL(src string) map[string][]Member

ParseUserGDSL parses a single user-authored GDSL file and returns the receiver-to-members map it declares.

Recognised structure (standard IntelliJ GDSL syntax):

// Variant 1 — ctype is the user-facing receiver name:
contributor(context(ctype: 'maven')) {
    method(name: 'setVersion', type: 'Object',
           params: [version: 'java.lang.String'],
           doc: 'Set Maven project version')
}

// Variant 2 — ctype is a fully-qualified class name; the user-facing
// receiver name is paired up in a separate top-level contributor block:
contributor(jenkinsContext) {
    property name: 'maven', type: 'be.cumulus.jenkins.dsl.MavenDsl'
}
contributor(context(ctype: 'be.cumulus.jenkins.dsl.MavenDsl')) {
    method name: 'setVersion', type: 'Object',
           params: [version: 'java.lang.String'],
           doc: '''Set Maven project version'''
}

Both invocation styles (paren + parenless) and both doc-string forms (single + triple-quoted) are accepted.

Any `method`/`property` declarations outside a contributor block are ignored — we deliberately don't let user files inject top-level steps.

Types

type GlobalVar

type GlobalVar struct {
	Name    string
	Doc     string   // plain text, HTML stripped
	Members []Member // methods/fields scraped from the doc (e.g. maven.goal)
}

GlobalVar is a globally accessible variable (`env`, `currentBuild`, a library-provided global).

func ParseGlobals

func ParseGlobals(htmlSrc string) []GlobalVar

ParseGlobals extracts global-variable docs from the pipeline-syntax/globals HTML page. Tolerates both the dt/dd and h1/section layouts.

type Member

type Member struct {
	Name      string
	Signature string  // e.g. "setVersion(version: String)"
	Doc       string  // free-form description
	Params    []Param // declared parameter names — drives in-call completion
}

Member is one callable or property on a GlobalVar. Sourced from user- provided GDSL files (or, for `params`, from the job's parameter definitions). Signature/doc may be empty when the source is terse.

type Param

type Param struct {
	Name  string
	Type  string // fully-qualified Java/Groovy type (e.g. "java.lang.String")
	Named bool   // true for namedParams entries (foo: bar), false for positional
}

Param is one parameter of a step's signature.

type Step

type Step struct {
	Name       string
	ReturnType string
	Params     []Param
	Doc        string // plain text, HTML stripped
}

Step is a callable pipeline step (`sh`, `git`, or a library-defined `var`).

func (Step) Signature

func (s Step) Signature() string

Signature renders a human-readable signature like "sh(script: String, returnStdout: boolean)".

type Symbols

type Symbols struct {
	Steps       []Step
	Globals     []GlobalVar
	DSLKeywords []string // declarative Pipeline DSL keywords (`pipeline`, `stages`, …)
	FetchedAt   time.Time
}

Symbols is the merged symbol set for a single build.