tools

Documentation

Overview

Package tools provides structures and methods for managing tool configurations, including downloading, validating, and executing tools in various environments. It supports different strategies for tool management such as upgrading, forcing installation, or skipping based on conditions and tags.

The package handles various aspects of tool setup, including resolving sources, handling aliases, managing environment variables, applying templates, and validating tool configurations. It also supports working with different platforms, allowing platform-specific handling of tools.

Index

• Variables
• func ExtensionsToHint(exts Extensions) match.Hint
• type Aliases
• type Checker
• type Checksum
• type Condition
• type Defaults
  • func (d *Defaults) Initialize() error
• type Exe
  • func (e *Exe) UnmarshalYAML(value *yaml.Node) error
• type Extensions
• type Fallbacks
• type Mode
  • func (m Mode) String() string
• type Settings
• type Skip
  • func (s Skip) True() (bool, string, error)
  • func (s *Skip) UnmarshalYAML(value *yaml.Node) error
• type Status
• type Strategy
  • func (s Strategy) Check(t *Tool) error
  • func (s Strategy) Upgrade(t *Tool) error
• type Tags
  • func (t *Tags) Append(tags ...string)
  • func (t Tags) Has(tags Tags) bool
  • func (t Tags) HasNot(tags Tags) bool
  • func (t *Tags) UnmarshalYAML(value *yaml.Node) error
• type Tool
  • func (t *Tool) ApplyDefaults(d Defaults)
  • func (t *Tool) CheckSkipConditions(withTags, withoutTags []string) error
  • func (t *Tool) Download() (string, file.File, error)
  • func (t *Tool) Exists() bool
  • func (t *Tool) Resolve(withTags, withoutTags []string) error
  • func (t *Tool) TemplateFirst() error
  • func (t *Tool) TemplateLast() error
  • func (t *Tool) ToTemplateMap(flatten ...map[string]any) map[string]any
  • func (t *Tool) UnmarshalYAML(value *yaml.Node) error
  • func (t *Tool) Validate() error
• type Tools
  • func (t *Tools) Load(cfg string) (err error)

Variables

var (
	// ErrAlreadyExists indicates that the tool already exists in the system.
	ErrAlreadyExists = fmt.Errorf("tool already exists")
	// ErrDoesHaveTags indicates that the tool has tags that are in the excluded tags list.
	ErrDoesHaveTags = fmt.Errorf("tool contains excluded tags")
	// ErrDoesNotHaveTags indicates that the tool does not contain required tags.
	ErrDoesNotHaveTags = fmt.Errorf("tool does not contain included tags")
	// ErrSkipped indicates that the tool has been skipped due to conditions.
	ErrSkipped = fmt.Errorf("tool skipped")
	// ErrFailed indicates that the tool has failed to install or resolve.
	ErrFailed = fmt.Errorf("tool failed")
)

Functions

func ExtensionsToHint

func ExtensionsToHint(exts Extensions) match.Hint

ExtensionsToHint converts a list of extensions into a match.Hint.

Types

type Aliases

type Aliases = unmarshal.SingleOrSlice[string]

Aliases represents a tool's alias names.

type Checker

type Checker struct {
	// Test defines the commands that should be run to test or validate the tool's functionality.
	Test command.Commands
	// Checksum is used for verifying the integrity of the tool (e.g., via a hash).
	Checksum Checksum
}

Checker represents a tool checker configuration.

type Checksum

type Checksum struct {
	// Path to the checksum file.
	Path string
	// Enabled specifies whether checksum verification is enabled.
	Enabled bool
}

Checksum represents a checksum configuration.

type Condition

type Condition struct {
	// Condition is a string that represents a boolean expression (e.g., "true" or "false") that determines whether the operation should be skipped.
	Condition string
	// Reason provides an optional explanation for why the operation is being skipped.
	Reason string
}

Condition defines a condition and an optional reason for skipping an operation.

type Defaults

type Defaults struct {
	// Exe specifies default executable details such as patterns for identifying the binary.
	Exe Exe
	// Output specifies the default output path for the tool.
	Output string
	// Platform defines default platform-specific settings (e.g., OS and architecture).
	Platform detect.Platform
	// Values contains default custom values for the tool configuration.
	Values map[string]any
	// Fallbacks defines default fallback configurations or sources in case the primary configuration fails.
	Fallbacks []string
	// Hints provide default matching patterns or heuristics for the tool.
	Hints match.Hints
	// Source defines the default source configuration for fetching the tool (e.g., GitHub, local files).
	Source sources.Source
	// Tags are default labels or markers for categorizing the tool.
	Tags Tags
	// Strategy defines the default deployment or fetching strategy for the tool.
	Strategy Strategy
	// Extensions lists default additional file extensions related to the tool.
	Extensions []string
	// Env defines default environment variables applied when running the tool.
	Env env.Env
	// Mode specifies the default operating mode for the tool (e.g., silent mode, verbose mode).
	Mode Mode
}

Defaults holds default configuration values for a tool. These values can be applied to a tool configuration to provide sensible defaults for executable paths, output locations, platform-specific settings, and more.

func (*Defaults) Initialize

func (d *Defaults) Initialize() error

Initialize detects the current platform and applies platform-specific defaults to the Defaults struct. It also sets up default extensions based on the detected platform.

type Exe

type Exe struct {
	// Name is the name under which the binary will be stored in the output folder.
	Name string
	// Patterns specifies the patterns used to locate the binary in the downloaded folder.
	// This can either be a single string or a slice of strings.
	Patterns unmarshal.SingleOrSlice[string]
}

Exe represents the configuration for the executable, including the name under which the binary will be stored and the patterns to search for the binary within the downloaded files.

func (*Exe) UnmarshalYAML

func (e *Exe) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements custom unmarshaling for Exe, allowing the YAML to either provide just the name as a scalar or the full Exe structure.

type Extensions

type Extensions = unmarshal.SingleOrSlice[string]

Extensions represents a collection of file extensions.

type Fallbacks

type Fallbacks = unmarshal.SingleOrSlice[sources.Type]

Fallbacks represents a collection of fallback sources for the tool. It can either be a single source type or a slice of source types, allowing flexibility in specifying multiple fallback methods if the primary source fails.

type Mode

type Mode string

Mode represents the operational mode for a tool, determining how the tool is handled. It could specify different behaviors such as extracting the tool from an archive or searching for the tool.

const (
	// Extract mode indicates that the tool should be extracted from an archive or compressed file.
	Extract Mode = "extract"
	// Find mode indicates that the tool should be located within a specified directory or environment.
	Find Mode = "find"
)

func (Mode) String

func (m Mode) String() string

String returns the string representation of the Mode.

type Settings

type Settings struct {
}

type Skip

type Skip []Condition

Skip represents a list of conditions under which certain operations (e.g., downloading, testing) should be skipped.

func (Skip) True

func (s Skip) True() (bool, string, error)

True checks if any condition in the Skip list evaluates to true. It returns a boolean indicating if the skip should occur, the associated reason, and any error encountered while evaluating the condition.

func (*Skip) UnmarshalYAML

func (s *Skip) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements custom unmarshaling for Skip, allowing the Skip field to be either a single condition or a list of conditions.

type Status

type Status int

const (
	OK                Status = 200
	BadRequest        Status = 400
	InternalServerErr Status = 500
)

type Strategy

type Strategy string

Strategy represents the strategy for handling tool installation or upgrades.

const (
	// None indicates no strategy, meaning no action will be taken if the tool already exists.
	None Strategy = "none"
	// Upgrade indicates that the tool should only be upgraded if a newer version is available.
	Upgrade Strategy = "upgrade"
	// Force indicates that the tool should be installed or updated regardless of its current state.
	Force Strategy = "force"
)

func (Strategy) Check

func (s Strategy) Check(t *Tool) error

Check verifies if the tool needs any action based on the current strategy. It returns an error if the tool already exists and the strategy is set to None.

func (Strategy) Upgrade

func (s Strategy) Upgrade(t *Tool) error

Upgrade checks if the tool should be upgraded based on the strategy and its current version. It compares the existing version with the desired version and returns an error if the tool is already up to date.

type Tags

type Tags []string

Tags represents a list of tags associated with a tool. Tags can be used to categorize or filter tools based on specific labels or keywords.

func (*Tags) Append

func (t *Tags) Append(tags ...string)

Append adds new tags to the Tags list, avoiding duplicates.

func (Tags) Has

func (t Tags) Has(tags Tags) bool

Has checks if any of the provided tags are present in the Tags list. Returns true if at least one tag matches.

func (Tags) HasNot

func (t Tags) HasNot(tags Tags) bool

HasNot checks if none of the provided tags are present in the Tags list. Returns true if none of the tags match.

func (*Tags) UnmarshalYAML

func (t *Tags) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements custom unmarshaling for Tags, allowing the field to be either a single string or a list of strings.

type Tool

type Tool struct {
	// Name of the tool, usually a short identifier or title.
	Name string
	// Description of the tool, giving more context about its purpose.
	Description string
	// Version specifies the version of the tool.
	Version string
	// Path represents the URL or file path where the tool can be fetched or downloaded from.
	Path string
	// Output defines the output path where the tool will be installed or extracted.
	Output string
	// Exe specifies the executable details for the tool, such as patterns or names for locating the binary.
	Exe Exe
	// Platform defines the platform-specific details for the tool, including OS and architecture constraints.
	Platform detect.Platform
	// Aliases represent alternative names or shortcuts for the tool.
	Aliases Aliases
	// Values contains custom values or variables used in the tool's configuration.
	Values map[string]any
	// Fallbacks defines fallback configurations in case the primary configuration fails.
	Fallbacks Fallbacks
	// Hints provide additional matching patterns or heuristics for the tool.
	Hints match.Hints
	// Source defines the source configuration, which determines how the tool is fetched (e.g., GitHub, local files).
	Source sources.Source
	// Tags are labels or markers that can be used to categorize or filter the tool.
	Tags Tags
	// Strategy defines how the tool is deployed, fetched, or managed (e.g., download strategies, handling retries).
	Strategy Strategy
	// Extensions lists additional files or behaviors that are tied to the tool.
	Extensions Extensions
	// Skip defines conditions under which certain steps (e.g., downloading, testing) are skipped.
	Skip Skip
	// Post defines commands that should be run after the main operation, such as post-installation steps.
	Post command.Commands
	// Mode defines the operating mode for the tool, potentially controlling behavior such as silent mode or verbose mode.
	Mode Mode
	// Settings contains custom settings or options that modify the behavior of the tool.
	Settings Settings
	// Env defines the environment variables that are applied when running the tool.
	Env env.Env
	// Check defines a set of instructions for verifying the tool's integrity or functionality.
	Check Checker
}

Tool represents a single tool configuration. It contains various fields that specify details such as the tool's name, version, path, execution settings, platform-specific settings, environment variables, and custom strategies for downloading, testing, or deploying.

func (*Tool) ApplyDefaults

func (t *Tool) ApplyDefaults(d Defaults)

ApplyDefaults applies default values to the Tool configuration. If a field is empty or nil, it is replaced with the corresponding default from the Defaults struct. TODO(Idelchi): Improve - what if someone wants a value to be ""?

func (*Tool) CheckSkipConditions

func (t *Tool) CheckSkipConditions(withTags, withoutTags []string) error

CheckSkipConditions verifies whether the tool should be skipped based on its tags or strategy.

func (*Tool) Download

func (t *Tool) Download() (string, file.File, error)

Download downloads the tool using its configured source and installer.

func (*Tool) Exists

func (t *Tool) Exists() bool

Exists checks if the tool's executable already exists in the output path.

func (*Tool) Resolve

func (t *Tool) Resolve(withTags, withoutTags []string) error

Resolve attempts to resolve the tool's source and strategy based on the provided tags. It handles fallbacks and applies templating to the tool's fields as needed.

func (*Tool) TemplateFirst

func (t *Tool) TemplateFirst() error

Template applies templating to various fields of the Tool struct, such as version, path, and checksum. It processes these fields using Go templates and updates them with the templated values.

func (*Tool) TemplateLast

func (t *Tool) TemplateLast() error

func (*Tool) ToTemplateMap

func (t *Tool) ToTemplateMap(flatten ...map[string]any) map[string]any

func (*Tool) UnmarshalYAML

func (t *Tool) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements custom unmarshaling for Tool with KnownFields check. This allows the Tool to be unmarshaled from YAML while verifying that only known fields are present, ensuring stricter validation and preventing unexpected fields.

func (*Tool) Validate

func (t *Tool) Validate() error

Validate validates the Tool's configuration using the validator package.

type Tools

type Tools []Tool

Tools represents a collection of Tool configurations.

func (*Tools) Load

func (t *Tools) Load(cfg string) (err error)

Load reads a tool configuration file and loads it into the Tools collection. If the configuration is not a YAML file, it assumes a tool is being referenced by name or URL and creates a simple tool entry.