gopolutils

package module
v1.35.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 22, 2026 License: MIT Imports: 4 Imported by: 2

README

gopolutils

Build Test Go Report Card Go Reference

Documentation

Overview

gopolutils provides numerious utilities standardizing logging, enum creation, exception handling, and internal version control. The example below describes a "Hello World" programme using a Logger and Exception.

Example: 

import "github.com/Polshkrev/gopolutils"

func main() {
	var logger *gopolutils.Logger = gopolutils.NewLogger("main", gopolutils.Debug)
	var except *gopolutils.Exception = logger.ConsoleOnly()
	if except != nil {
		panic(except)
	}
	logger.Log("Hello World", gopolutils.Debug)

}

A simple use case for the Version is release flags.

As an example: 

import "github.com/Polshkrev/gopolutils"

var version *gopolutils.Version = gopolutils.VersionConvert(0, 1, 0)

func main() {
	if !version.IsPublic() {
		// code/functionality to expose when the internal version becomes public.
	}
	panic("This is not the code you're looking for.")
}

Or in a more verbose way: 

import (
	"fmt"
	"os"

	"github.com/Polshkrev/gopolutils"
)

var version *gopolutils.Version = gopolutils.VersionConvert(0, 1, 0)

func main() {
	if !version.IsPublic() {
		// code/functionality to expose when the internal version becomes public.
	}
	fmt.Fprintln(os.Stderr, gopolutils.NewNamedException(gopolutils.ValueError, "All your code is belong to us."))
	os.Exit(1)
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Must added in v1.11.0 

func Must[Type any](result Type, except *Exception) Type

If the given exception is not nil, the function panics, else the function returns the given result.

Types

type ByteSize added in v1.31.0 

type ByteSize Size

Standardization of a unit byte scaler. 

const (
	Byte ByteSize = 1 << (10 * iota) // Unit size in bytes.
	KB                               // Unit size in kilobytes.
	MB                               // Unit size in megabytes.
	GB                               // Unit size in gigabytes.
	TB                               // Unit size in terabytes.
	PB                               // Unit size in petabytes.
	EB                               // Unit size in exabytes.
)

func (ByteSize) String added in v1.35.0 

func (size ByteSize) String() string

Represent a ByteSize as a string. Returns a suffix string representation of a unit byte scaler.

type Enum added in v1.18.0 

type Enum uint8

Standardization of a enum value.

type Exception 

type Exception struct {
	// contains filtered or unexported fields
}

Representation of a standardized exception.

func NewException 

func NewException(format string, arguments ...any) *Exception

Construct a new exception with a default name and a given message. Returns a pointer to a new exception.

func NewNamedException 

func NewNamedException(name ExceptionName, format string, arguments ...any) *Exception

Construct a new exception with a given name and format specifiers with arguments. Returns a pointer to a new exception.

func (Exception) Error 

func (exception Exception) Error() string

Method to adhere to the built-in error type. Returns a string representation of the exception.

func (Exception) Is added in v1.15.0 

func (exception Exception) Is(name ExceptionName) bool

Determine if the exception has a specific name. Similar to the errors.Is function in the standard library. Returns true if the exception has the given name, else false.

func (Exception) Message added in v1.10.0 

func (exception Exception) Message() string

Obtain the raw message of the exception without the name. Returns the message of the exception.

func (Exception) Name added in v1.10.0 

func (exception Exception) Name() ExceptionName

Obtain the name of the exception. Returns the name of the exception.

type ExceptionName added in v1.15.0 

type ExceptionName StringEnum

Finite list of named exceptions. Inspired by python's built-in exceptions. 

const (
	BaseException          ExceptionName = "Exception"
	ArithmeticError        ExceptionName = "ArithmeticError"        // For any miscellaneous arithmatic exception.
	OverflowError          ExceptionName = "OverflowError"          // For any overflow.
	UnderflowError         ExceptionName = "UnderflowError"         // For any underflow.
	ZeroDivisionError      ExceptionName = "ZeroDivisionError"      // When dividing by zero.
	AssertionError         ExceptionName = "AssertionError"         // For any failed assertion.
	EOFError               ExceptionName = "EOFError"               // When reaching the end of a file or buffer.
	LookupError            ExceptionName = "LookupError"            // When any miscellaneous lookup fails.
	OutOfRangeError        ExceptionName = "OutOfRangeError"        // For any indexed access outside of the allotted range.
	IndexError             ExceptionName = "IndexError"             // For any indexed access.
	KeyError               ExceptionName = "KeyError"               // For any keyed access.
	OSError                ExceptionName = "OSError"                // For any miscellaneous operating system exception.
	IOError                ExceptionName = "IOError"                // For any miscellaneous io exceptions.
	BlockingIOError        ExceptionName = "BlockingIOError"        // For any miscellaneous blocking io exception.
	ChildProcessError      ExceptionName = "ChildProcessError"      // For any miscellaneous child process exception.
	ConnectionError        ExceptionName = "ConnectionError"        // For any miscellaneous connection exception.
	BrokenPipeError        ExceptionName = "BrokenPipeError"        // For any exception relating to a broken pipe.
	ConnectionAbortedError ExceptionName = "ConnectionAbortedError" // For an aborted connection.
	ConnectionRefusedError ExceptionName = "ConnectionRefusedError" // For a refused connection.
	ConnectionResetError   ExceptionName = "ConnectionResetError"   // For a reset connection.
	FileExistsError        ExceptionName = "FileExistsError"        // When a file exists already in the file system.
	FileNotFoundError      ExceptionName = "FileNotFoundError"      // When a file cannot be found.
	IsADirectoryError      ExceptionName = "IsADirectoryError"      // When an accessed file is a directory.
	NotADirectoryError     ExceptionName = "NotADirectoryError"     // When an accessed directory is not a directory.
	PermissionError        ExceptionName = "PermissionError"        // When an accessed file or endpoint does not have the correct permissions
	ProcessLookupError     ExceptionName = "ProcessLookupError"     // For a porcess lookup fail.
	TimeoutError           ExceptionName = "TimeoutError"           // For a timeout occurrence.
	RuntimeError           ExceptionName = "RuntimeError"           // For any miscellaneous runtime exception.
	NotImplementedError    ExceptionName = "NotImplementedError"    // For any unimplemented methods or functions.
	ValueError             ExceptionName = "ValueError"             // For any miscellaneous value exception.
	UnreachableError       ExceptionName = "UnreachableError"       // For an unreachable case.
)

type Future added in v1.30.0 

type Future[Type any] struct {
	// contains filtered or unexported fields
}

Python-like concurrent future.

func Async added in v1.30.0 

func Async[Type any](caller func() (Type, *Exception)) *Future[Type]

Create an async Future based on a given callback. If the child process fails, a ChildProcessError is returned.

func (*Future[Type]) Await added in v1.30.0 

func (future *Future[Type]) Await() (Type, *Exception)

Await a Future. The exception state is dependant on the Future's child process.

type Logger added in v0.0.3 

type Logger struct {
	// contains filtered or unexported fields
}

A logger.

func NewLogger added in v0.0.3 

func NewLogger(name string, level LoggingLevel) *Logger

Construct a new logger with a given name and default logging level. The default logging level passed into this constructor is the minimum level of severity that will be output by the logger. Returns a pointer to a new logger.

func (*Logger) AddConsole added in v0.0.3 

func (logger *Logger) AddConsole() *Exception

Bind the standard output to the logger. If the logger has already allocated the maximum number of allowed outputs, a ValueError is returned.

func (*Logger) AddFile added in v0.0.3 

func (logger *Logger) AddFile(fileName string) *Exception

Bind a file to the logger. If the logger has already allocated the maximum number of allowed outputs, a ValueError is returned. If the given file can not be found, an IOError is returned.

func (*Logger) Close added in v0.0.4 

func (logger *Logger) Close()

Deallocate the logger. If the logger has a file bound, the file will need to be closed with this method. A good practice is to call this method deferred even if a file is not bound; this method will not close the standard output.

func (*Logger) ConsoleOnly added in v0.0.3 

func (logger *Logger) ConsoleOnly() *Exception

Bind only the standard output to the logger. If the logger has already allocated the maximum number of allowed outputs, a ValueError is returned.

func (*Logger) FileOnly added in v0.0.3 

func (logger *Logger) FileOnly(fileName string) *Exception

Bind only a file to the logger. If the logger has already allocated the maximum number of allowed outputs, a ValueError is returned. If the given file can not be found, an Exception is returned.

func (*Logger) FullSetup added in v0.0.3 

func (logger *Logger) FullSetup(fileName string) *Exception

Bind both a file and the standard output to the logger. If the logger has already allocated the maximum number of allowed outputs, a ValueError is returned. If the given file can not be found, an Exception is returned.

func (Logger) GetLevel added in v1.11.0 

func (logger Logger) GetLevel() LoggingLevel

Obtain the level of the logger. Returns the level of the logger.

func (Logger) GetName added in v1.11.0 

func (logger Logger) GetName() string

Obtain the name of the logger. Returns the name of the logger.

func (*Logger) Log added in v0.0.6 

func (logger *Logger) Log(message string, level LoggingLevel)

Log a message. If the default logging level of the logger is greater than the given logging level of the message, the message will not be logged.

func (*Logger) SetLevel added in v1.5.0 

func (logger *Logger) SetLevel(level LoggingLevel)

Set the minimal logging level for the logger.

func (*Logger) SetName added in v1.11.0 

func (logger *Logger) SetName(name string)

Set the name of the logger.

type LoggingLevel added in v0.0.3 

type LoggingLevel Enum

An Enum representation of the severity of a log message. 

const (
	// Lowest severity log message. Used to log debug information for development.
	Debug LoggingLevel = iota
	// Used to log info that should be read. It is not an error, but is not a debug message.
	Info
	// Used to log a non-crashing warning, such as a file already existing when calling a create function.
	Warning
	// Used to log a non-crashing error. This level should be the default when logging an error.
	Error
	// Used to log a crashing error. Used to log a message of a panic or breaking state.
	Critical
)

func (LoggingLevel) String added in v1.35.0 

func (level LoggingLevel) String() string

Represent a LoggingLevel as a string. Returns a string representation of a logging level. If the logging level is not defined in the enum, an UnreachableError is returned.

type Number added in v1.35.0 

type Number interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64
}

Representation of a generic number type.

type Size added in v1.23.0 

type Size uint64

Standardization of a size of a type or collection.

type StringEnum added in v1.18.0 

type StringEnum string

Standardization of a enum string value.

type Version 

type Version struct {
	// contains filtered or unexported fields
}

Representation of a semantic versioning object.

func NewFullVersion 

func NewFullVersion(name, description string, major, minor, patch uint8) *Version

Construct a full initialized version object. Returns a pointer to a new fully initialized version object.

func NewNamedVersion 

func NewNamedVersion(name string) *Version

Construct a new version object initialized with a given name. Returns a pointer to a new version object initialized with the given name.

func NewStringVersion 

func NewStringVersion(name, description string) *Version

Construct a new version object with each of its string properties initialized. Returns a pointer to a new version object initialized with the given string parametres.

func NewVersion 

func NewVersion() *Version

Construct a new zero-initialized version object. All the string properties are empty and the numeric properties are set to zero. Returns a pointer to a new version object.

func VersionConvert 

func VersionConvert(major, minor, patch uint8) *Version

Construct a new version object with given numeric values. The string properties of the version object are empty. Returns a pointer to a new version object with each of the numeric properties initialized with the given parametres.

func (Version) Compare 

func (version Version) Compare(operand Version) bool

Compare each of the numeric properties of the version object to a given operand. Returns true if each of the version object's properties are greater than or equal to the given operand's numeric properties.

func (Version) CompareMajor 

func (version Version) CompareMajor(major uint8) bool

Determine if the version object's major property is greater than or equal to the given operand. Returns true if the version object's major property is greater than or equal to the given operand.

func (Version) CompareMinor 

func (version Version) CompareMinor(minor uint8) bool

Determine if the version object's minor property is greater than or equal to the given operand. Returns true if the version object's minor property is greater than or equal to the given operand.

func (Version) ComparePatch 

func (version Version) ComparePatch(patch uint8) bool

Determine if the version object's patch property is greater than or equal to the given operand. Returns true if the version object's patch property is greater than or equal to the given operand.

func (Version) Description 

func (version Version) Description() string

Access the description property of the version object. Returns the description property of the version object.

func (*Version) Fix 

func (version *Version) Fix()

Increment the version object's patch property. The version object's major and minor property are not modified.

func (Version) IsPublic 

func (version Version) IsPublic() bool

Determine if the version object is public. Returns true if the version object's major property is evaluated greater than or equal to 1.

func (Version) IsZero added in v1.5.0 

func (version Version) IsZero() bool

Determine if the version object is equal to zero. Returns true if each of the version object's numeric properties are equal to zero, else false.

func (Version) Major 

func (version Version) Major() uint8

Access the major property of the version object. Returns the major property of the version object.

func (Version) Minor 

func (version Version) Minor() uint8

Access the minor property of the version object. Returns the minor property of the version object.

func (Version) Name 

func (version Version) Name() string

Access the name property of the version object. Returns the name property of the version object.

func (Version) NumberString added in v1.6.0 

func (version Version) NumberString() string

Render a string representation of the version object's numeric properties. Returns the version object's numeric properties represented as a string.

func (Version) Patch 

func (version Version) Patch() uint8

Access the patch property of the version object. Returns the patch property of the version object.

func (*Version) Publish 

func (version *Version) Publish() *Exception

Publish a version object. Set the version object's major property to 1. Zero-out all other numeric properties. If the version object is evaluated to have already been published, a ValueError is returned and no properties are modified.

func (*Version) Release 

func (version *Version) Release()

Increment the version object's major property. The version object's minor and patch properties are set to 0.

func (*Version) SetDescription 

func (version *Version) SetDescription(description string)

Set the description property of the version object.

func (*Version) SetMajor 

func (version *Version) SetMajor(major uint8)

Set the major property of the version object.

func (*Version) SetMinor 

func (version *Version) SetMinor(minor uint8)

Set the minor property of the version object.

func (*Version) SetName 

func (version *Version) SetName(name string)

Set the name property of the version object.

func (*Version) SetPatch 

func (version *Version) SetPatch(patch uint8)

Set the patch property of the version object.

func (Version) String added in v1.35.0 

func (version Version) String() string

Render a string representation of the version object. Returns a version object represented as a string.

func (*Version) Update 

func (version *Version) Update()

Increment the version object's minor property. The version object's patch property is set to 0. The version object's major version is not modified.

Source Files

View all Source files

Directories

Path Synopsis
Collections provide interfaces of standardization for operations related to data structures.
 Collections provide interfaces of standardization for operations related to data structures.
safe
Safe provides interfaces of standardization for operations related to concurrent safe data structures.
 Safe provides interfaces of standardization for operations related to concurrent safe data structures.
fayl provides numerious utilities pertaining to the creation, destruction, serialization, and manipulation of files and their corresponding paths on the filesystem.
 fayl provides numerious utilities pertaining to the creation, destruction, serialization, and manipulation of files and their corresponding paths on the filesystem.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.