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.

Expand ▾ Collapse ▴

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.