github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/cmd/go/internal/script/state.go (about)

     1  // Copyright 2022 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package script
     6  
     7  import (
     8  	"github.com/shogo82148/std/bytes"
     9  	"github.com/shogo82148/std/context"
    10  	"github.com/shogo82148/std/internal/txtar"
    11  	"github.com/shogo82148/std/io"
    12  )
    13  
    14  // A State encapsulates the current state of a running script engine,
    15  // including the script environment and any running background commands.
    16  type State struct {
    17  	engine *Engine
    18  
    19  	ctx    context.Context
    20  	cancel context.CancelFunc
    21  	file   string
    22  	log    bytes.Buffer
    23  
    24  	workdir string
    25  	pwd     string
    26  	env     []string
    27  	envMap  map[string]string
    28  	stdout  string
    29  	stderr  string
    30  
    31  	background []backgroundCmd
    32  }
    33  
    34  // NewState returns a new State permanently associated with ctx, with its
    35  // initial working directory in workdir and its initial environment set to
    36  // initialEnv (or os.Environ(), if initialEnv is nil).
    37  //
    38  // The new State also contains pseudo-environment-variables for
    39  // ${/} and ${:} (for the platform's path and list separators respectively),
    40  // but does not pass those to subprocesses.
    41  func NewState(ctx context.Context, workdir string, initialEnv []string) (*State, error)
    42  
    43  // CloseAndWait cancels the State's Context and waits for any background commands to
    44  // finish. If any remaining background command ended in an unexpected state,
    45  // Close returns a non-nil error.
    46  func (s *State) CloseAndWait(log io.Writer) error
    47  
    48  // Chdir changes the State's working directory to the given path.
    49  func (s *State) Chdir(path string) error
    50  
    51  // Context returns the Context with which the State was created.
    52  func (s *State) Context() context.Context
    53  
    54  // Environ returns a copy of the current script environment,
    55  // in the form "key=value".
    56  func (s *State) Environ() []string
    57  
    58  // ExpandEnv replaces ${var} or $var in the string according to the values of
    59  // the environment variables in s. References to undefined variables are
    60  // replaced by the empty string.
    61  func (s *State) ExpandEnv(str string, inRegexp bool) string
    62  
    63  // ExtractFiles extracts the files in ar to the state's current directory,
    64  // expanding any environment variables within each name.
    65  //
    66  // The files must reside within the working directory with which the State was
    67  // originally created.
    68  func (s *State) ExtractFiles(ar *txtar.Archive) error
    69  
    70  // Getwd returns the directory in which to run the next script command.
    71  func (s *State) Getwd() string
    72  
    73  // Logf writes output to the script's log without updating its stdout or stderr
    74  // buffers. (The output log functions as a kind of meta-stderr.)
    75  func (s *State) Logf(format string, args ...any)
    76  
    77  // LookupEnv retrieves the value of the environment variable in s named by the key.
    78  func (s *State) LookupEnv(key string) (string, bool)
    79  
    80  // Path returns the absolute path in the host operating system for a
    81  // script-based (generally slash-separated and relative) path.
    82  func (s *State) Path(path string) string
    83  
    84  // Setenv sets the value of the environment variable in s named by the key.
    85  func (s *State) Setenv(key, value string) error
    86  
    87  // Stdout returns the stdout output of the last command run,
    88  // or the empty string if no command has been run.
    89  func (s *State) Stdout() string
    90  
    91  // Stderr returns the stderr output of the last command run,
    92  // or the empty string if no command has been run.
    93  func (s *State) Stderr() string