config

Documentation

Overview

Package config handles configuration of the app.

The config file is in yaml format for easy readability. Create a default config file in the current working directory using the -init flag.

A config is handled one of three ways:

• If a file exists at the path, it is attempted to be parsed as a valid config file.
• If a file does not exists at the path, the built-in defaults are used after a warning is shown about the missing file.
• If the path is blank, the default config is used.

This package must not import any other packages from within this repo to prevent import loops (besides minor utility packages) since the config package is most likely read by nearly all other packages in this repo.

When adding a new field to the config file:

• Add the field to the File type below.
• Determine any default value(s) for the field and set it in newDefaultConfig().
• Set validation in validate().
• Document the field as needed (README, other documentation).

Index

• Constants
• func CreateDefaultConfig() (err error)
• func Read(path string, print bool) (err error)
• type File
  • func Data() *File
  • func (conf *File) IsDirectoryToIgnore(path string) bool
  • func (conf *File) IsExtensionToWatch(extension string) bool
  • func (conf *File) IsRebuildExtension(extension string) bool
  • func (conf *File) IsTempDir(path string) (yes bool, err error)
  • func (conf *File) OverrideTags(t string)
  • func (conf *File) OverrideVerbose(v bool)
  • func (conf *File) UsingDefaults() bool

Constants

const DefaultConfigFileName = "fresher.conf"

DefaultConfigFileName is the typical name of the config file.

Functions

func CreateDefaultConfig

func CreateDefaultConfig() (err error)

CreateDefaultConfig creates a config file in the current directory with the default configuration. This is mostly used to create a template config file to modify. Used/called by the -init flag.

func Read

func Read(path string, print bool) (err error)

Read handles reading and parsing the config file at the provided path and saving it to the package's parsedConfig variable for future use. The parsed data is sanitized and validated. The print argument is used to print the config as it was read/parsed and as it was understood after sanitizing, validating, and handling default values.

If a config file is not found at the given path, a warning is shown and the built-in default config is used instead. Use -init to create a default config file.

Types

type File

type File struct {
	//WorkingDir is the path to the working directory, the directory `go run` or
	//`go build` would be executed in.
	WorkingDir string `yaml:"WorkingDir"`

	//EntryPoint is the relative path to directory where the "main" package is located
	//based off the directory fresher is being run from.
	//
	//This really only needs to be modified if your "main" package is located in a
	//subdirectory of your repo, such as "cmd/x". In this case, you cannot just run
	//fresher in "cmd/x" since any file changes made outside of "cmd/x" would not be
	//recognized and thus the binary will not be rebuild/rerun.
	EntryPoint string `yaml:"EntryPoint"`

	//TempDir is the directory off of WorkingDir where fresher will store the built
	//binary, that will be run, and error logs.
	TempDir string `yaml:"TempDir"`

	//ExtensionsToWatch is the list of file extensions to watch for changes, typically
	//.go and .html (if building a web app).
	ExtensionsToWatch []string `yaml:"ExtensionsToWatch"`

	//NoRebuildExtensions is the list of extensions that the binary will be restarted
	//on when file changes occur, but the binary won't be rebuilt. Any extension
	//listed here should, obviously, be listed in ExtensionsToWatch as well.
	//
	//For example, if an .html file is changed, the binary would need to be restarted
	//since HTML files are typically stored in memory (using html/templates) when the
	//binary is first started.
	NoRebuildExtensions []string `yaml:"NoRebuildExtensions"`

	//DirectoriesToIgnore is the list of directories that won't be watched for file
	//change events. Typically directories such as .git, node_modules, etc.
	DirectoriesToIgnore []string `yaml:"DirectoriesToIgnore"`

	//BuildDelayMilliseconds is the delay between a file change event occuring and
	//`go build` being run. This delay is helpful to prevent unnecessary buildng when
	//multiple file change events occur in quick succession.
	//
	//This was inherited from the "github.com/gravityblast/fresh" and may not be
	//needed any longer since running `go build`s will be cancelled if a new file
	//change event occurs.
	BuildDelayMilliseconds int64 `yaml:"BuildDelayMilliseconds"`

	//BuildName is the name of the binary output by `go build` and saved to TempDir.
	BuildName string `yaml:"BuildName"`

	//BuildLogFilename is the name of file saved in TempDir where build errors will
	//be logged to. This file will contain output from `go build` and is useful for
	//analyzing errors rather then looking at output in terminal.
	BuildLogFilename string `yaml:"BuildLogFilename"`

	//GoTags is anything provided to `go run` or `go build` -tags flag.
	//
	//Any tags provided in the config, from file or defaults, are overridden by
	//anything provided to the -tags flag provided to fresher. This was done to
	//alleviate the need to always edit a config file for handling -tags changes.
	GoTags string `yaml:"GoTags"`

	//GoLdflags is anything provided to `go build` -ldflags flag.
	//See https://pkg.go.dev/cmd/link for possible options.
	GoLdflags string `yaml:"GoLdflags"`

	//GoTrimpath determines if the -trimpath flag should be passed to `go build`.
	//Typically this isn't needed since the built binary won't be distributed since
	//fresher is designed for development use only.
	//See https://pkg.go.dev/cmd/go#:~:text=but%20still%20recognized.)%0A%2D-,trimpath,-remove%20all%20file.
	GoTrimpath bool `yaml:"GoTrimpath"`

	//Flags is the list of flags you provide to your binary or `go run`, such as
	//`go run main.go -flag1="test"`.
	Flags string `yaml:"Flags"`

	//Verbose causes fresher to output more logging. Use for diagnostics when
	//determining which files/directories/extensions are being watched and when file
	//change events are occuring.
	Verbose bool `yaml:"Verbose"`
	// contains filtered or unexported fields
}

File defines the list of configuration fields. The value for each field will be set by a default or read from a config file. The config file is typically stored in the same directory as the executable.

Don't use uints! If user provided a negative number an ugly error message is kicked out. We would rather check for the negative number here and provide a nicer error message.

Struct tags are needed for working with yaml.v2 package, otherwise the package expects fields to start with lower case characters. However, if we lower cased all the struct field names, then we wouldn't be able to access those fields in other packages.

If adding or updating a field here, make sure to document it in README.md!

func Data

func Data() *File

Data returns the package level saved config. This is used in other packages to access the parsed config file.

func (*File) IsDirectoryToIgnore

func (conf *File) IsDirectoryToIgnore(path string) bool

IsDirectoryToIgnore returns true if the given path is in the DirectoriesToIgnore.

func (*File) IsExtensionToWatch

func (conf *File) IsExtensionToWatch(extension string) bool

IsExtensionToWatch returns true if the given path contains an extension we should watch for changes.

func (*File) IsRebuildExtension

func (conf *File) IsRebuildExtension(extension string) bool

IsRebuildExtension returns true if the given extension is not in the NoRebuildExtensions list.

func (*File) IsTempDir

func (conf *File) IsTempDir(path string) (yes bool, err error)

IsTempDir returns true if the given path represents the same directory as TempDir. We use absolute paths here since we want to be certain if the path given matches the same underlying directory as given in TempDir.

func (*File) OverrideTags

func (conf *File) OverrideTags(t string)

OverrideTags sets the Tags field to t. This is used when the -tags flag was provided and overrides the value stored in parsedConfig's Tags field. This is useful for changing tags without having to edit the config file (if it exists) each time.

func (*File) OverrideVerbose

func (conf *File) OverrideVerbose(v bool)

OverrideVerbose sets the Verbose field to v. This is used when the -verbose flag was provided and overrides the value stored in teh parsedConfig's Verbose field. This is useful for when (1) you aren't using a config file (i.e.: the default running method of fresher), or (2) you have a config file and just want some extra logging on a case-by-case basis.

func (*File) UsingDefaults

func (conf *File) UsingDefaults() bool

UsingDefaults returns true is usingbuildInDefaults is set to true.