Documentation
¶
Index ¶
- Constants
- Variables
- func AppDataDir(withAppIdentifier bool) string
- func AppDir() (string, error)
- func AppLogDir(withAppIdentifier bool) string
- func CancelRunAtExit(id int)
- func Copy(src, dst string) error
- func CopyWithMask(src, dst string, mask fs.FileMode) error
- func Copyright() string
- func CopyrightYears() string
- func CurrentUserName() string
- func EnsureAtSignalHandlersAreInstalled()
- func Exit(status int)
- func ExitIfErr(err error)
- func ExitWithErr(err error)
- func ExitWithMsg(msg string)
- func FileExists(path string) bool
- func FileIsReadable(path string) bool
- func FontDirs() []string
- func HomeDir() string
- func IsDir(path string) bool
- func LongAppVersion() string
- func MoveFile(src, dst string) error
- func Must[T any](v T, err error) T
- func OpenBrowser(pathOrURL string) error
- func PanicRecovery(handler func(error))
- func RunAtExit(f func()) int
- func SafeCall(f func(), handler func(error))
- func ShortAppVersion() string
- func WriteSafeFile(filename string, writer func(io.Writer) error) (err error)
- type SafeFile
- type TaskQueue
- type TaskQueueConfig
Constants ¶
const ( MacOS = "darwin" WindowsOS = "windows" LinuxOS = "linux" )
Constants for comparison to runtime.GOOS
Variables ¶
var ( // AppCmdName holds the application's name as specified on the command line. AppCmdName string // AppName holds the name of the application. By default, this is the same as AppCmdName. AppName string // CopyrightStartYear holds the starting year to place in the copyright banner. If not set explicitly, will be set // to the year of the "vcs.time" build tag. CopyrightStartYear string // CopyrightEndYear holds the ending year to place in the copyright banner. If not set explicitly, will be set to // the year of the "vcs.time" build tag. CopyrightEndYear string // CopyrightHolder holds the name of the copyright holder. CopyrightHolder string // License holds the license the software is being distributed under. This is intended to be a simple one line // description, such as "Mozilla Public License 2.0" and not the full license itself. License string // AppVersion holds the application's version information. If not set explicitly, will be the version of the main // module or "0.0" if that isn't available. Unfortunately, this automatic setting only works for binaries created // using `go install <package>@<version>`. AppVersion string // VCSName holds the name of the version control system and is set to the value of the build tag "vcs". VCSName string // VCSVersion holds the vcs revision and is set to the value of the build tag "vcs.revision". VCSVersion string // VCSModified is true if the "vcs.modified" build tag is true. VCSModified bool // BuildNumber holds the build number. If not set explicitly, will be generated from the value of the build tag // "vcs.time". BuildNumber string // AppIdentifier holds the uniform type identifier (UTI) for the application. This should contain only alphanumeric // (A-Z,a-z,0-9), hyphen (-), and period (.) characters. The string should also be in reverse-DNS format. For // example, if your company’s domain is ajax.com and you create an application named Hello, you could assign the // string com.ajax.Hello as your AppIdentifier. AppIdentifier string )
var ( // ExitRecoveryHandler will be used to capture any panics caused by functions that have been installed when run // during exit. By default, this will be nil, which means the panics will be logged. ExitRecoveryHandler func(err error) // ExitCodeForSIGINT is the exit code used when the program is terminated by a SIGINT (Ctrl+C). Defaults to 1. ExitCodeForSIGINT = 1 // ExitCodeForSIGTERM is the exit code used when the program is terminated by a SIGTERM. Defaults to 1. ExitCodeForSIGTERM = 1 )
Functions ¶
func AppDataDir ¶
AppDataDir returns the path to use for user-specific data for the application. The returned path uses platform separators and may need to be created before use.
func AppDir ¶
AppDir returns the absolute path to the logical directory the application resides within. The returned path uses platform separators. For macOS, this means the directory where the .app bundle resides, not the binary that's tucked down inside it.
func AppLogDir ¶
AppLogDir returns the application log directory. The returned path uses platform separators and may need to be created before use.
func CancelRunAtExit ¶
func CancelRunAtExit(id int)
CancelRunAtExit unregisters a function that was previously registered by xos.RunAtExit(). If the ID is no longer present, nothing happens. Calling xos.CancelRunAtExit() after xos.Exit() has been called will have no effect.
func CopyWithMask ¶
CopyWithMask src to dst. src may be a directory, file, or symlink.
func Copyright ¶
func Copyright() string
Copyright returns the copyright notice. If no copyright years have been set, an empty string will be returned.
func CopyrightYears ¶
func CopyrightYears() string
CopyrightYears returns the copyright years, either as a single year or as a range of years, e.g. "2025" or "2016-2025".
func CurrentUserName ¶
func CurrentUserName() string
CurrentUserName returns the current user's name. This will attempt to retrieve the user's display name, but will fall back to the account name if it isn't available.
func EnsureAtSignalHandlersAreInstalled ¶
func EnsureAtSignalHandlersAreInstalled()
EnsureAtSignalHandlersAreInstalled ensures that the signal handlers for SIGINT and SIGTERM are installed. If they are already installed, this function does nothing. This will be called automatically by RunAtExit() if the signal handlers have not yet been installed.
func Exit ¶
func Exit(status int)
Exit runs any registered exit functions in the inverse order they were registered and then exits the progream with the specified status. If a previous call to xos.Exit() is already being handled, this method does nothing and does not return. Recursive calls to xos.Exit() will trigger a panic, which the exit handling will catch and report, but will then proceed with exit as normal. Note that once xos.Exit() is called, no subsequent changes to the registered list of functions will have an effect.
func ExitIfErr ¶
func ExitIfErr(err error)
ExitIfErr checks the error and if it isn't nil, calls xos.ExitWithErr(err).
func ExitWithErr ¶
func ExitWithErr(err error)
ExitWithErr logs the error and then exits with code 1.
func ExitWithMsg ¶
func ExitWithMsg(msg string)
ExitWithMsg writes the message to stderr and then exits with code 1.
func FileExists ¶
FileExists returns true if the path points to a regular file.
func FileIsReadable ¶
FileIsReadable returns true if the path points to a regular file that we have permission to read.
func FontDirs ¶
func FontDirs() []string
FontDirs returns the standard font directories, in order of priority. The returned paths use platform separators and may not exist.
func HomeDir ¶
func HomeDir() string
HomeDir returns the current user's home directory. The returned path uses platform separators.
func LongAppVersion ¶
func LongAppVersion() string
LongAppVersion returns a combination of the app version and the build number. If the code was built from a dirty version of a VCS checkout, a trailing '~' character will be added.
func MoveFile ¶
MoveFile moves a file in the file system or across volumes, using rename if possible, but falling back to copying the file if not. This will error if either src or dst are not regular files.
func Must ¶ added in v2.10.0
Must is a helper function that takes a value of any type and an error. If the error is nil, it returns the value; if the error is non-nil, it panics.
func OpenBrowser ¶
OpenBrowser asks the system to open the provided path or URL.
func PanicRecovery ¶
func PanicRecovery(handler func(error))
PanicRecovery provides an easy way to run code that may panic. If the handler is nil, the panic will be logged as an error.
Typical usage:
func RunSomeCode() {
defer xos.PanicRecovery(nil /* or provide a handler function */)
// ... run the code here ...
}
func RunAtExit ¶
func RunAtExit(f func()) int
RunAtExit registers a function to be run when xos.Exit() is called. Returns an ID that can be used to remove the function later, if needed. Calling xos.RunAtExit() after xos.Exit() has been called will have no effect.
func SafeCall ¶
func SafeCall(f func(), handler func(error))
SafeCall calls the provided function, safely wrapped by xos.PanicRecovery().
func ShortAppVersion ¶
func ShortAppVersion() string
ShortAppVersion returns the app version. If the code was built from a dirty version of a VCS checkout, a trailing '~' character will be added.
Types ¶
type SafeFile ¶
SafeFile provides safe overwriting of files. Instead of truncating and overwriting the destination file, it creates a temporary file in the same directory, writes to it, then renames the temporary file to the original name when Commit() is called. If Close() is called without calling Commit(), or the Commit() fails, then the original file is left untouched.
func CreateSafeFile ¶
CreateSafeFile creates a temporary file in the same directory as filename, which will be renamed to the given filename when calling Commit.
func (*SafeFile) Close ¶
Close the temporary file and remove it, if it hasn't already been committed. If it has been committed, nothing happens.
func (*SafeFile) Commit ¶
Commit the data into the original file and remove the temporary file from disk. Close() may still be called, but will do nothing.
func (*SafeFile) OriginalName ¶
OriginalName returns the original filename passed into CreateSafeFile().
type TaskQueue ¶
type TaskQueue struct {
// contains filtered or unexported fields
}
TaskQueue holds the queue information.
func NewTaskQueue ¶
func NewTaskQueue(config *TaskQueueConfig) *TaskQueue
NewTaskQueue creates an asynchronous queue which executes the tasks submitted to it.
type TaskQueueConfig ¶
type TaskQueueConfig struct {
// RecoveryHandler is the recovery handler to use for tasks that panic. If the handler is nil, the panic will be
// logged as an error.
RecoveryHandler func(error)
// Depth controls the maximum depth of the queue. Calls to Submit() will block when this number of tasks are already
// pending execution. Zero or less means to use an unbounded queue.
Depth int
// Workers controls the number of workers that will simultaneously process tasks. If set to 1, tasks submitted to
// the queue will be executed serially. If set to less than 1, the number of logical CPUs + 1 will be used instead.
Workers int
}
TaskQueueConfig provides configuration for a TaskQueue.
Source Files