README

Essentials by aah framework

Essentials contains simple & useful util functions for Go. aah framework utilizes essentials (aka `ess`) library across. Essentials library complements to standard packages, refer Godoc to know more.

Build Status Code Coverage Go Report Card Release Version Godoc

News

  • v0.8.0 released and tagged on Jun 20, 2018.

Installation

go get -u aahframework.org/essentials.v0

Visit official website https://aahframework.org to learn more about aah framework.

Documentation

Overview

Package ess provides simple & useful util functions for Go. aah framework utilizes essentials library across.

Index

Constants

View Source
const (
	ByteSize     = 1.0
	KiloByteSize = 1024 * ByteSize
	MegaByteSize = 1024 * KiloByteSize
	GigaByteSize = 1024 * MegaByteSize
	TeraByteSize = 1024 * GigaByteSize
)

Byte unit value

View Source
const StringEmpty = ""

StringEmpty is empty string constant. Using `ess.StringEmpty` instead of "".

Variables

View Source
var (
	// FmtFlagSeparator is used parse flags pattern.
	FmtFlagSeparator = "%"

	// FmtFlagValueSeparator is used to parse into flag and value.
	FmtFlagValueSeparator = ":"
)
View Source
var (
	ErrGoPathIsNotSet = errors.New("GOPATH environment variable is not set. " +
		"Please refer to https://golang.org/doc/code.html to configure your Go environment")

	ErrDirNotInGoPath = errors.New("current directory is outside of GOPATH")
)

Required variables

View Source
var ErrBase64Decode = errors.New("encoding/base64: decode error")

ErrBase64Decode returned when given string unable to do base64 decode.

View Source
var Version = "0.8.0"

Version no. of essentials library

Functions

func ApplyFileMode

func ApplyFileMode(target string, mode os.FileMode) error

ApplyFileMode applies the given file mode to the target{file|directory}

func CloseQuietly

func CloseQuietly(c ...interface{})

CloseQuietly closes `io.Closer` quietly. Very handy, where you do not care about error while `Close()` and helpful for code quality too.

func CopyDir

func CopyDir(dest, src string, excludes Excludes) error

CopyDir copies entire directory, sub directories and files into destination and it excludes give file matches

func CopyFile

func CopyFile(dest, src string) (int64, error)

CopyFile copies the given source file into destination

func DecodeBase64

func DecodeBase64(v []byte) ([]byte, error)

DecodeBase64 method decodes given base64 into bytes. Reference: https://github.com/golang/go/blob/master/src/encoding/base64/base64.go#L384

func DeleteFiles

func DeleteFiles(files ...string) (errs []error)

DeleteFiles method deletes give files or directories. ensure your supplying appropriate paths.

func DirsPath

func DirsPath(basePath string, recursive bool) (pdirs []string, err error)

DirsPath method returns all directories absolute path from given base path recursively.

func DirsPathExcludes

func DirsPathExcludes(basePath string, recursive bool, excludes Excludes) (pdirs []string, err error)

DirsPathExcludes method returns all directories absolute path from given base path recursively excluding the excludes list.

func EncodeToBase64

func EncodeToBase64(v []byte) []byte

EncodeToBase64 method encodes given bytes into base64 bytes. Reference: https://github.com/golang/go/blob/master/src/encoding/base64/base64.go#L169

func FilesPath

func FilesPath(basePath string, recursive bool) (files []string, err error)

FilesPath method returns all files absolute path from given base path recursively.

func FilesPathExcludes

func FilesPathExcludes(basePath string, recursive bool, excludes Excludes) (files []string, err error)

FilesPathExcludes method returns all files absolute path from given base path recursively excluding the excludes list.

func GenerateRandomKey

func GenerateRandomKey(length int) []byte

GenerateRandomKey method generates the random bytes for given length using `math/rand.Source` and byte mask. StackOverflow Ref - http://stackoverflow.com/a/31832326

func GenerateSecureRandomKey

func GenerateSecureRandomKey(length int) []byte

GenerateSecureRandomKey method generates the random bytes for given length using `crypto/rand`.

func GoPath

func GoPath() (string, error)

GoPath returns GOPATH in context with current working directory otherwise it returns first directory from GOPATH

func IsAbsURL

func IsAbsURL(rawurl string) bool

IsAbsURL method returns true if given raw URL is absolute URL otherwise false.

func IsDir

func IsDir(path string) bool

IsDir returns true if the given `path` is directory otherwise returns false. Also returns false if path is not exists

func IsDirEmpty

func IsDirEmpty(path string) bool

IsDirEmpty returns true if the given directory is empty also returns true if directory not exists. Otherwise returns false

func IsFileExists

func IsFileExists(filename string) bool

IsFileExists return true is file or directory is exists, otherwise returns false. It also take cares of symlink path as well

func IsImportPathExists

func IsImportPathExists(path string) bool

IsImportPathExists returns true if import path found in the GOPATH otherwise returns false

func IsInGoRoot

func IsInGoRoot(path string) bool

IsInGoRoot returns true if given path has prefix of GOROOT otherwise false

func IsRelativeURL

func IsRelativeURL(rawurl string) bool

IsRelativeURL method returns true if given raw URL is relative URL otherwise false.

func IsSliceContainsString

func IsSliceContainsString(strSlice []string, search string) bool

IsSliceContainsString method checks given string in the slice if found returns true otherwise false.

func IsStrEmpty

func IsStrEmpty(v string) bool

IsStrEmpty returns true if strings is empty otherwise false

func IsVaildURL

func IsVaildURL(rawurl string) bool

IsVaildURL method returns true if given raw URL gets parsed without any errors otherwise false.

func LineCnt

func LineCnt(fileName string) int

LineCnt counts no. of lines on file

func LineCntr

func LineCntr(r io.Reader) int

LineCntr counts no. of lines for given reader

func LookExecutable

func LookExecutable(name string) bool

LookExecutable looks for an executable binary named file in the directories named by the PATH environment variable.

func MkDirAll

func MkDirAll(path string, mode os.FileMode) error

MkDirAll method creates nested directories with given permission if not exists

func NewGUID

func NewGUID() string

NewGUID method returns a new Globally Unique Identifier (GUID).

The 12-byte `UniqueId` consists of-

- 4-byte value representing the seconds since the Unix epoch,
- 3-byte machine identifier,
- 2-byte process id, and
- 3-byte counter, starting with a random value.

Uses Mongo Object ID algorithm to generate globally unique ids - https://docs.mongodb.com/manual/reference/method/ObjectId/

func RandomString

func RandomString(length int) string

RandomString method generates the random string for given length using `math/rand.Source` and byte mask.

func SecureRandomString

func SecureRandomString(length int) string

SecureRandomString method generates the random string for given length using `crypto/rand`.

func StrToBytes

func StrToBytes(value string) (int64, error)

StrToBytes method returns bytes value for given string value.

For e.g.:
  2mb ==> 2097152 bytes
  2MB ==> 2097152 bytes
  2MiB ==> 2097152 bytes

func StripExt

func StripExt(name string) string

StripExt method returns name of the file without extension.

E.g.: index.html => index

func Walk

func Walk(srcDir string, walkFn filepath.WalkFunc) error

Walk method extends filepath.Walk to also follows symlinks. Always returns the path of the file or directory also path is inline to name of symlink

func Zip

func Zip(dest, src string) error

Zip method creates zip archive for given file or directory.

Types

type CallerInfo

type CallerInfo struct {
	QualifiedName string
	FunctionName  string
	FileName      string
	File          string
	Line          int
}

CallerInfo struct stores Go caller info

func GetCallerInfo

func GetCallerInfo() *CallerInfo

GetCallerInfo method returns caller's QualifiedName, FunctionName, File, FileName, Line Number.

type Excludes

type Excludes []string

Excludes is handly filepath match manipulation

func (*Excludes) Match

func (e *Excludes) Match(file string) bool

Match evalutes given file with available patterns returns true if matches otherwise false. `Match` internally uses the `filepath.Match`

Note: `Match` ignore pattern errors, use `Validate` method to ensure you have correct exclude patterns

func (*Excludes) Validate

func (e *Excludes) Validate() error

Validate helps to evalute the pattern are valid `Match` method is from error and focus on match

type FmtFlag

type FmtFlag uint8

FmtFlag type definition

type FmtFlagPart

type FmtFlagPart struct {
	Flag   FmtFlag
	Name   string
	Format string
}

FmtFlagPart is indiviual flag details

For e.g.:
  part := FmtFlagPart{
    Flag:   FmtFlagTime,
    Name:   "time",
    Format: "2006-01-02 15:04:05.000",
  }

func ParseFmtFlag

func ParseFmtFlag(pattern string, fmtFlags map[string]FmtFlag) ([]FmtFlagPart, error)

ParseFmtFlag it parses the given pattern, format flags into format flag parts.

For e.g.:
  %time:2006-01-02 15:04:05.000 %level:-5 %message
  %clientip %reqid %reqtime %restime %resstatus %ressize %reqmethod %requrl %reqhdr:Referer %reshdr:Server

type FunctionInfo

type FunctionInfo struct {
	Name          string
	Package       string
	QualifiedName string
}

FunctionInfo structs Go function info

func GetFunctionInfo

func GetFunctionInfo(f interface{}) (fi *FunctionInfo)

GetFunctionInfo method returns the function name for given interface value.

type Valuer

type Valuer interface {
	Get(key string) interface{}
	Set(key string, value interface{})
}

Valuer interface is general purpose to `Set` and `Get` operations.