# README
README
Table of Contents
Table of Contents
Name
go-minor - minor Go additions
The minor package contains minor1 enhancements to the Go standard library and other open source packages.
Version
This documentation is for go-minor version v1.0.0
Synopsis
package main
import (
"log"
"github.com/kjmjonline/go-minor"
"github.com/rs/zerolog"
)
func main() {
// Let's use FilePathInCwd to get the fully qualified file name
// of the file to write logs to in the current working directory
var filepath string
var err error
if filepath, err = minor.FilePathInCwd("my-project.log"); err != nil {
log.Fatal(err)
}
// Now we will initialize the zerlogo logging to this file
if err = minor.SetGlobalZerologToFile(filepath, zerolog.DebugLevel); err != nil {
log.Fatal(err)
}
log.Print(
"At this point we can log using the global zerolog logger",
)
...
// We can also use minor.CaptureOutput to capture and test any output
}
Description
This package contains some trivial functions that are needed by kjmjonline.
It contains a zerolog helper function SetGlobalZerologToFile to setup the zerolog logging facility.
Fully qualified file paths for files in the current working directory can be determined with the FilePathInCwd function.
The CaptureOutput function can be used to get any ouput from a function. This can be used, for instance, to verify that the function is working correctly.
The Go compiler does an excellent job of catching any unused symbols in your code. You can, however, use the IgnoreUnused function to silence these errors, for instance during development.
Installation
go get -u -v github.com/kjmjonline/go-minor@latest
This will install go-minor and its dependencies to your go/pkg
directory.
Public Functions
CaptureOutput
Captures, and returns, the merged stdout and stderr output of a
function.
package main
import (
"fmt"
"github.com/kjmjonline/go-minor"
)
func sayHello() {
fmt.Print("Hello, stranger!")
}
func main() {
greeting, err := minor.CaptureOutput(sayHello)
// `greeting` will contain "Hello, stranger!" here
if err == nil {
fmt.Println(greeting)
}
}
FilePathInCwd
Returns the full path to the given fileName in the current work directory
(i.e., equivalent to cwd in *nix systems).
The current directory is the directory that this program was started from. This may be different from the directory that the executable is in.
package main
import (
"fmt"
"github.com/kjmjonline/go-minor"
)
func main() {
fileName := "blort.txt"
// i.e., the path plus the filename
var filePath string
var err error
if filePath, err = minor.FilePathInCwd(fileName); err != nil {
panic(err)
}
fmt.Print(filePath)
// If the current directory (the directory this program was
// started from) is "/tmp" then the`filePath` returned would be:
// "/tmp/blort.txt".
}
IgnoreUnused
Silences Go errors caused when code contains any unused constants, variables, and/or functions.
To silence these errors pass the name of each unused identifier to this function.
package main
import (
// We can ignore unused package import errors by preceding the
// unused package with un underscore character:
_ "fmt"
"github.com/kjmjonline/go-minor"
)
const unusedConst = 42
type unusedType struct{}
var trulyUnusedVar string
func someUnusedFunc() string {
return "this function is not used"
}
func main() {
# We can ignore unused types like this:
var _ unusedType
# And here we ignore any unused constants, variables, and functions
minor.IgnoreUnused(
unusedConst,
trulyUnusedVar,
someUnusedFunc,
)
}
SetGlobalZerologToFile
This function sets up the global zerolog logger.
The log file is created, or is appended to if it already exists.
Logging is set up to create log entries with the current time timestamp, and file name and line numbers where the log entries were created. The timestamps use the RFC 3339 Nano time format, which has sub-second precision.
The log messages are colored. If you do not want colored logs you could create a utility to remove the color escape character sequences.
package main
import (
sl "log"
"github.com/kjmjonline/go-minor"
"github.com/rs/zerolog/log"
"github.com/rs/zerolog/pkgerrors"
)
func main() {
err := minor.SetGlobalZerologToFile("mylog", zerolog.DebugLevel)
if err != nil {
sl.Fatal(err)
}
// log.Print() is similar to log.Debug().Msg()
log.Print("global zerolog has been created")
err := errors.New("Whoa!")
wrapped := errors.WithStack(err)
log.Error().Stack().Err(wrapped).Msg("An error with a stacktrace")
}
Dependencies
go-minor uses some packages that are not part of the Go standard library. These libraries are automatically installed when go-minor is installed.
They are:
- github.com/rs/zerolog
What!? That's it!
Bugs and Limitations
This package has no known bugs or limitations.
Please report any incompatibilities to [email protected].
Acknowledgements
The CaptureOutput, FilePathInCwd, and IgnoreUnused functions were adopted from other sources that have been lost to the mists of time.
The functions have been changed slightly.
Please report any missing acknowledgements to [email protected].
Author
Justin Hanekom
Copyright and License
Copyright (c) 2024 Justin Hanekom
This file is part of go-minor - minor enhancements to Go libraries.
go-minor is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
go-minor is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with go-minor. If not, see https://www.gnu.org/licenses/.
Footnotes
-
miniscule, really! ↩