Documentation

Overview

    Package annotation implements a state machine that constructs Milo annotation protobufs from a series of annotation commands.

    The annotation state is represented by a State object. Annotation strings are appended to the State via Append(), causing the State to incorporate that annotation and advance. During state advancement, any number of the State's Callbacks may be invoked in response to changes that are made.

    State is pure (not bound to any I/O). Users of a State should interact with it by implementing Callbacks.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type Callbacks

    type Callbacks interface {
    	// StepClosed is called when a Step has closed. An Updated callback will still
    	// be invoked.
    	StepClosed(*Step)
    	// Updated is called when a Step's state has been updated.
    	Updated(*Step, UpdateType)
    	// StepLogLine is called when a Step emits a log line.
    	StepLogLine(s *Step, stream types.StreamName, label, line string)
    	// StepLogEnd is called when a Step finishes emitting logs.
    	StepLogEnd(*Step, types.StreamName)
    }

      Callbacks is the set of callbacks that a State may invoke as it processes annotations.

      type Execution

      type Execution struct {
      	Name    string
      	Command []string
      	Dir     string
      	Env     map[string]string
      }

        Execution describes the high-level execution metadata.

        func ProbeExecution

        func ProbeExecution(argv, env []string, cwd string) *Execution

          ProbeExecution loads Execution parameters by probing the current runtime environment.

          type State

          type State struct {
          	// LogNameBase is the base log stream name that is prepeneded to generated
          	// log streams.
          	LogNameBase types.StreamName
          	// Callbacks implements annotation callbacks. It may not be nil.
          	Callbacks Callbacks
          	// Execution is the supplied Execution. If nil, no execution details will be
          	// added to the generated annotation protos.
          	Execution *Execution
          	// Offline specifies whether parsing happens not at the same time as
          	// emitting. If true and CURRENT_TIMESTAMP annotations are not provided
          	// then step start/end times are left empty.
          	Offline bool
          	// Clock is the clock implementation to use for time information.
          	// Defaults to system time.
          	Clock clock.Clock
          	// contains filtered or unexported fields
          }

            State is the aggregate annotation state for a given annotation stream. It receives updates in the form of annotations added via Append, and can be serialized to an annotation state protobuf.

            func (*State) Append

            func (s *State) Append(annotation string) error

              Append adds an annotation to the state. If the state was updated, Append will return true.

              The appended annotation should only contain the annotation text body, not any annotation indicators (e.g., "@@@") that surround it.

              If the annotation is invalid or could not be added to the state, an error will be returned.

              Steps and descriptions can be found at: https://chromium.googlesource.com/chromium/tools/build/+/master/scripts/ master/chromium_step.py

              func (*State) CurrentStep

              func (s *State) CurrentStep() *Step

                CurrentStep returns the step referenced by the step cursor.

                func (*State) Finish

                func (s *State) Finish()

                  Finish closes the top-level annotation state and any outstanding steps.

                  func (*State) LookupStep

                  func (s *State) LookupStep(name string) *Step

                    LookupStep returns the step with the supplied name, or nil if no such step exists.

                    If multiple steps share a name, this will return the latest registered step with that name.

                    func (*State) LookupStepErr

                    func (s *State) LookupStepErr(name string) (*Step, error)

                      LookupStepErr returns the step with the supplied name, or an error if no such step exists.

                      If multiple steps share a name, this will return the latest registered step with that name.

                      func (*State) ResolveStep

                      func (s *State) ResolveStep(ms *annopb.Step) *Step

                        ResolveStep returns the annotation package *Step corresponding to the supplied *annopb.Step. This is a reverse lookup operation.

                        If the supplied *annopb.Step is not registered with this annotation State, this function will return nil.

                        func (*State) RootStep

                        func (s *State) RootStep() *Step

                          RootStep returns the root step.

                          func (*State) SetCurrentStep

                          func (s *State) SetCurrentStep(v *Step)

                            SetCurrentStep sets the current step. If the supplied step is nil, the root step will be used.

                            The supplied step must already be registered with the State.

                            type Step

                            type Step struct {
                            	annopb.Step
                            
                            	// logNameBase is the LogDog stream name root for this step.
                            	LogNameBase types.StreamName
                            	// contains filtered or unexported fields
                            }

                              Step represents a single step.

                              func (as *Step) AddLogdogStreamLink(server, label string, prefix, name types.StreamName)

                                AddLogdogStreamLink adds a LogDog stream link to this Step's links list.

                                func (*Step) AddStep

                                func (as *Step) AddStep(name string, legacy bool) *Step

                                  AddStep generates a new substep.

                                  func (*Step) AddText

                                  func (as *Step) AddText(text string) bool

                                    AddText adds a line of step component text.

                                    func (as *Step) AddURLLink(label, alias, url string)

                                      AddURLLink adds a URL link to this Step's links list.

                                      func (*Step) BaseStream

                                      func (as *Step) BaseStream(name types.StreamName) types.StreamName

                                        BaseStream returns the supplied name prepended with this Step's base log name.

                                        For example, if the base name is "foo/bar", BaseStream("baz") will return "foo/bar/baz".

                                        func (*Step) ClearSummary

                                        func (as *Step) ClearSummary()

                                          ClearSummary clears the step's summary text.

                                          func (*Step) ClearText

                                          func (as *Step) ClearText() bool

                                            ClearText clears step component text.

                                            func (*Step) Close

                                            func (as *Step) Close(closeTime *timestamp.Timestamp) bool

                                              Close closes this step and any outstanding resources that it owns. If it is already closed, does not have side effects and returns false.

                                              func (*Step) LogEnd

                                              func (as *Step) LogEnd(label string)

                                                LogEnd ends the log for the specified label.

                                                func (*Step) LogLine

                                                func (as *Step) LogLine(label, line string) bool

                                                  LogLine emits a log line for a specified log label.

                                                  func (*Step) Name

                                                  func (as *Step) Name() string

                                                    Name returns the step's component name.

                                                    func (*Step) Proto

                                                    func (as *Step) Proto() *annopb.Step

                                                      Proto returns the annotation Step protobuf associated with this Step.

                                                      func (*Step) SetNestLevel

                                                      func (as *Step) SetNestLevel(l int) bool

                                                        SetNestLevel sets the nest level of this Step, and identifies its nesting parent.

                                                        If no parent could be found at level "l-1", the root step will become the parent.

                                                        func (*Step) SetProperty

                                                        func (as *Step) SetProperty(name, value string) bool

                                                          SetProperty sets a key/value property for this Step.

                                                          func (*Step) SetSTDERRStream

                                                          func (as *Step) SetSTDERRStream(st *annopb.LogdogStream) (updated bool)

                                                            SetSTDERRStream sets the LogDog STDERR stream value, returning true if the Step was updated.

                                                            func (*Step) SetSTDOUTStream

                                                            func (as *Step) SetSTDOUTStream(st *annopb.LogdogStream) (updated bool)

                                                              SetSTDOUTStream sets the LogDog STDOUT stream value, returning true if the Step was updated.

                                                              func (*Step) SetStatus

                                                              func (as *Step) SetStatus(s annopb.Status, fd *annopb.FailureDetails) bool

                                                                SetStatus sets this step's component status.

                                                                If the status doesn't change, the supplied failure details will be ignored.

                                                                func (*Step) SetSummary

                                                                func (as *Step) SetSummary(value string) bool

                                                                  SetSummary sets the Step's summary text.

                                                                  The summary is implemented as the first line of step component text. If no summary is currently defined, one will be inserted; otherwise, the current summary will be replaced.

                                                                  func (*Step) Start

                                                                  func (as *Step) Start(startTime *timestamp.Timestamp) bool

                                                                    Start marks the Step as started.

                                                                    func (*Step) String

                                                                    func (as *Step) String() string

                                                                    type UpdateType

                                                                    type UpdateType int

                                                                      UpdateType is information sent to the Updated callback to indicate the nature of the update.

                                                                      const (
                                                                      	// UpdateIterative indicates that a non-structural update occurred.
                                                                      	UpdateIterative UpdateType = iota
                                                                      	// UpdateStructural indicates that a structural update has occurred. A
                                                                      	// structural update is one that affects the existence of or relationship of
                                                                      	// the Steps in the annotation.
                                                                      	UpdateStructural
                                                                      )