is

README

is

is provides numerous detectors for checking the states of environment (build, executive, ...).

Features

• is.State(which) bool: the universal detector entry - via RegisterStateGetter(state string, getter func() bool) to add your own ones. Since v0.5.11
• is.Env() holds a global struct for CLI app basic states, such as: verbose/quiet/debug/trace....
• is.InDebugging() bool, is.InTesting() bool, and is.InTracing() bool, ....
• is.DebugBuild() bool.
• is.K8sBuild() bool, is.DockerBuild() bool, ....
• is.ColoredTty() bool, ....
• is.Color() to get an indexer for the functions in our term/color subpackage, ...
• Terminal Colorizer, Detector, unescape tools.
• stringtool: RandomStringPure, case-converters ...
• basics: closable, closer, signals.
  • easier Press any key to exit... prompt: is.Signals().Catch()
• go 1.21+ required

To using environment detecting utilities better and smoother, some terminal (and stringtool, basics) tools are bundled together.

Usages

package main

import (
    "context"
    "fmt"
    "log/slog"
    "os"
    "sync"
    "time"

    "github.com/hedzr/is"
    "github.com/hedzr/is/basics"
    "github.com/hedzr/is/term/color"
)

func main() {
    defer basics.Close()

    is.RegisterStateGetter("custom", func() bool { return is.InVscodeTerminal() })

    println(is.InTesting())
    println(is.State("in-testing"))
    println(is.State("custom")) // detects a state with custom detector
    println(is.Env().GetDebugLevel())
    if is.InDebugMode() {
        slog.SetDefault(slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{AddSource: true, Level: slog.LevelDebug})))
    }

    // or:
    //    is.Color().GetColorTranslator().Translate("<b>bold</b>")
    fmt.Printf("%v", color.GetCPT().Translate(`<code>code</code> | <kbd>CTRL</kbd>
        <b>bold / strong / em</b>
        <i>italic / cite</i>
        <u>underline</u>
        <mark>inverse mark</mark>
        <del>strike / del </del>
        <font color="green">green text</font>
`, color.FgDefault))

    ctx, cancel := context.WithCancel(context.Background())
    catcher := is.Signals().Catch()
    catcher.
        WithPrompt("Press CTRL-C to quit...").
        WithOnLoop(dbStarter, cacheStarter, mqStarter).
        WithOnSignalCaught(func(sig os.Signal, wg *sync.WaitGroup) {
            println()
            slog.Info("signal caught", "sig", sig)
            cancel() // cancel user's loop, see Wait(...)
        }).
        Wait(func(stopChan chan<- os.Signal, wgDone *sync.WaitGroup) {
            slog.Debug("entering looper's loop...")
            go func() {
                // to terminate this app after a while automatically:
                time.Sleep(10 * time.Second)
                stopChan <- os.Interrupt
            }()
            <-ctx.Done()  // waiting until any os signal caught
            wgDone.Done() // and complete myself
        })
}

func dbStarter(stopChan chan<- os.Signal, wgDone *sync.WaitGroup) {
    // initializing database connections...
    // ...
    wgDone.Done()
}

func cacheStarter(stopChan chan<- os.Signal, wgDone *sync.WaitGroup) {
    // initializing redis cache connections...
    // ...
    wgDone.Done()
}

func mqStarter(stopChan chan<- os.Signal, wgDone *sync.WaitGroup) {
    // initializing message queue connections...
    // ...
    wgDone.Done()
}

Result is similar with:

NOTE that is.Signals().Catch() will produce a prompt and enter a infinite loop to wait for user's keystroke pressed.

Lists

is.Terminal(os.Stdout)

The partials:

• is.InDebugging / InDebugMode

• is.DebuggerAttached (relyes on delve tag)

• is.InTracing / InTestingT

• is.InTesting / InTestingT

• is.InDevelopingTime

• is.InVscodeTerminal

• is.InK8s

• is.InIstio

• is.InDocker / InDockerEnvSimple

• Build

  • is.K8sBuild
  • is.IstioBuild
  • is.DockerBuild
  • is.VerboseBuild
  • is.DebugBuild
  • buildtags.IsBuildTagExists

• States / Env

  • VerboseModeEnabled
  • GetVerboseLevel / SetVerboseMode / SetVerboseLevel
  • QuietModeEnabled
  • GetQuietLevel / SetQuietMode / SetQuietLevel
  • NoColorMode
  • GetNoColorLevel / SetNoColorMode / SetNoColorLevel
  • DebugMode
  • GetDebugLevel / SetDebugMode / SetDebugLevel
  • Tracing
  • TraceMode
  • GetTraceLevel / SetTraceMode / SetTraceLevel

• Terminal / Tty

  • is.Terminal(file)
  • is.TerminalFd(fd)
  • is.Tty(wr)
  • is.ColoredTty(wr)
  • is.AnsiEscaped(s) (IsTtyEscaped(s))
  • StripEscapes(s)
  • ReadPassword
  • GetTtySize
  • is.GetTtySizeByName(filename) (cols,rows,err)
  • is.GetTtySizeByFile(file) (cols,rows,err)
  • is.GetTtySizeByFd(fd) (cols,rows,err)
  • StartupByDoubleClick() bool

• [Special] Terminal / Color

  • escaping tools: GetCPT()/GetCPTC()/GetCPTNC()
  • Highlight, Dimf, Text, Dim, ToDim, ToHighlight, ToColor, ...

• Basics

  • closers
    • Peripheral, Closable, Closer
    • RegisterClosable
    • RegisterClosers
    • RegisterCloseFns
  • is.Signals().Catcher()
  • is.FileExists(filepath)
  • is.ToBool, StringToBool

Build Tags

Some functions want special buildtags presented. These are including:

• verbose: See VerboseBuild, ...
• delve: See DebugBuild, ...
• k8s: See K8sBuild
• istio: See IstioBuild
• docker: See DockerBuild
• ...
• buildtags.IsBuildTagExists(tag) bool

Colorizes

The test codes:

import "github.com/hedzr/is/term/color"

func TestGetCPT(t *testing.T) {
t.Logf("%v", color.GetCPT().Translate(`<code>code</code> | <kbd>CTRL</kbd>
    <b>bold / strong / em</b>
    <i>italic / cite</i>
    <u>underline</u>
    <mark>inverse mark</mark>
    <del>strike / del </del>
    <font color="green">green text</font>
    `, color.FgDefault))
}

Result:

And more:

func TestStripLeftTabs(t *testing.T) {
t.Logf("%v", color.StripLeftTabs(`
    
        <code>code</code>
    NC Cool
     But it's tight.
      Hold On!
    Hurry Up.
    `))
}

func TestStripHTMLTags(t *testing.T) {
t.Logf("%v", color.StripHTMLTags(`
    
        <code>code</code>
    NC Cool
     But it's tight.
      Hold On!
    Hurry Up.
    `))
}

Basics (Closers)

The Closers() collects all closable objects and allow shutting down them at once.

package main

import (
    "os"

    "github.com/hedzr/is/basics"
)

type redisHub struct{}

func (s *redisHub) Close() {
    // close the connections to redis servers
    println("redis connections closed")
}

func main() {
    defer basics.Close()

    tmpFile, _ := os.CreateTemp(os.TempDir(), "1*.log")
    basics.RegisterClosers(tmpFile)

    basics.RegisterCloseFn(func() {
        // do some shutdown operations here
        println("close single functor")
    })

    basics.RegisterPeripheral(&redisHub{})
}

Basics (Signals)

Signals() could catch os signals and entering a infinite loop.

For example, a tcp server could be:

package main

import (
    "context"
    "os"
    "sync"

    "github.com/hedzr/go-socketlib/net"
    "github.com/hedzr/is"
    logz "github.com/hedzr/logg/slog"
)

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    logger := logz.New("new-dns")
    server := net.NewServer(":7099",
        net.WithServerOnListening(func(ss net.Server, l stdnet.Listener) {
            go runClient(ctx, ss, l)
        }),
        net.WithServerLogger(logger.WithSkip(1)),
    )
    defer server.Close()

    catcher := is.Signals().Catch()
    catcher.
        // WithVerboseFn(func(msg string, args ...any) {
        //     logz.WithSkip(2).Verbose(fmt.Sprintf("[verbose] %s", fmt.Sprintf(msg, args...)))
        // }).
        WithOnSignalCaught(func(sig os.Signal, wg *sync.WaitGroup) {
            println()
            logz.Debug("signal caught", "sig", sig)
            if err := server.Shutdown(); err != nil {
                logz.Error("server shutdown error", "err", err)
            }
            cancel()
        }).
        Wait(func(stopChan chan<- os.Signal, wgShutdown *sync.WaitGroup) {
            logz.Debug("entering looper's loop...")

            server.WithOnShutdown(func(err error, ss net.Server) { wgShutdown.Done() })
            err := server.ListenAndServe(ctx, nil)
            if err != nil {
                logz.Fatal("server serve failed", "err", err)
            }
        })
}

func runClient(ctx context.Context, ss net.Server, l stdnet.Listener) {
    c := net.NewClient()

    if err := c.Dial("tcp", ":7099"); err != nil {
        logz.Fatal("connecting to server failed", "err", err, "server-endpoint", ":7099")
    }
    logz.Info("[client] connected", "server.addr", c.RemoteAddr())
    c.RunDemo(ctx)
}

some packages has stayed in progress so the above codes is just a skeleton (from go-socketlib/_examples/new-loop/main.go/v1).

Contributions

Kindly welcome, please issue me first for keeping this repo smaller.

License

under Apache 2.0

Documentation

Index

• func AnsiEscaped(s string) bool
• func Closers() closerS
• func Color() color.Index
• func ColoredTty(w io.Writer) bool
• func DebugBuild() bool
• func DebugMode() bool
• func DebuggerAttached() bool
• func Detected(stateName string) (state bool)
• func DockerBuild() bool
• func Env() states.CmdrMinimal
• func FileExists(filepath string) bool
• func GetDebugLevel() int
• func GetNoColorLevel() int
• func GetQuietLevel() int
• func GetTraceLevel() int
• func GetTtySize() (cols, rows int)
• func GetTtySizeByFd(fd uintptr) (cols, rows int, err error)
• func GetTtySizeByFile(f *os.File) (cols, rows int, err error)
• func GetTtySizeByName(fn string) (cols, rows int, err error)
• func GetVerboseLevel() int
• func InDebugMode() bool
• func InDebugging() bool
• func InDevelopingTime() (status bool)
• func InDocker() bool
• func InDockerEnvSimple() (status bool)
• func InIstio() bool
• func InK8s() bool
• func InK8sYN() bool
• func InTesting() bool
• func InTestingT(args []string) bool
• func InTracing() bool
• func InVscodeTerminal() bool
• func IstioBuild() bool
• func K8sBuild() bool
• func NoColorMode() bool
• func QuietModeEnabled() bool
• func ReadFile(filename string) ([]byte, error)
• func ReadPassword() (text string, err error)
• func RegisterStateGetter(state string, getter func() bool)
• func SetDebugLevel(hits int)
• func SetDebugMode(b bool)
• func SetNoColorLevel(hits int)
• func SetNoColorMode(b bool)
• func SetQuietLevel(hits int)
• func SetQuietMode(b bool)
• func SetTraceLevel(hits int)
• func SetTraceMode(b bool)
• func SetVerboseLevel(hits int)
• func SetVerboseMode(b bool)
• func Signals() signalS
• func StartupByDoubleClick() bool
• func State(stateName string) (state bool)
• func States() states.CmdrMinimal
• func StringToBool(val string, defaultVal ...bool) (ret bool)
• func StripEscapes(str string) (strCleaned string)
• func Terminal(f *os.File) bool
• func TerminalFd(fd uintptr) bool
• func ToBool(val any, defaultVal ...bool) (ret bool)
• func TraceMode() bool
• func Tracing() bool
• func Tty(w io.Writer) bool
• func TtyEscaped(s string) bool
• func UpdateEnvWith(env states.CmdrMinimal)
• func VerboseBuild() bool
• func VerboseModeEnabled() bool

Functions

func AnsiEscaped

func AnsiEscaped(s string) bool

AnsiEscaped detects a string if it contains ansi color escaped sequences

func Closers

func Closers() closerS

Closers returns the container includes all registered closable objects.

The simplest ways is using package level Close function:

func main() {
    defer is.Closers().Close()

    // others statements ...

    is.Closers().RegisterCloseFns(func(){ sth.Close() })

    // more statements...
}

func Color

func Color() color.Index

Color returns an indexer for term/color subpackage.

For example, call the Translator to convert the html tags to color codes in a string:

is.Color().GetColorTranslator().Translate("<b>bold</b>")

func ColoredTty

func ColoredTty(w io.Writer) bool

ColoredTty detects a writer if it is a colorful tty device.

A colorful tty device can receive ANSI escaped sequences and draw its.

func DebugBuild

func DebugBuild() bool

func DebugMode

func DebugMode() bool

func DebuggerAttached

func DebuggerAttached() bool

DebuggerAttached returns status if debugger attached or is a debug build.

See also InDebugging.

To check wildly like cli app debug mode (via --debug), call InDebugMode

To find the parent process is dlv (that is, detecting a real debugger present), another library needed.

func Detected

func Detected(stateName string) (state bool)

Detected returns the detected state associated with the given state name.

= State, see also it.

func DockerBuild

func DockerBuild() bool

func Env

func Env() states.CmdrMinimal

func FileExists

func FileExists(filepath string) bool

FileExists detects if a file or a directory is existed.

func GetDebugLevel

func GetDebugLevel() int

func GetNoColorLevel

func GetNoColorLevel() int

func GetQuietLevel

func GetQuietLevel() int

func GetTraceLevel

func GetTraceLevel() int

func GetTtySize

func GetTtySize() (cols, rows int)

GetTtySize returns the window size in columns and rows in the active console window. The return value of this function is in the order of cols, rows.

func GetTtySizeByFd

func GetTtySizeByFd(fd uintptr) (cols, rows int, err error)

GetTtySizeByFd retrieve terminal window size by fd (file-descriptor). such as [os.Stdout.Fd()]

func GetTtySizeByFile

func GetTtySizeByFile(f *os.File) (cols, rows int, err error)

GetTtySizeByFile retrieve terminal window size by *os.File object. such as os.Stdout

func GetTtySizeByName

func GetTtySizeByName(fn string) (cols, rows int, err error)

GetTtySizeByName retrieve terminal window size by device name. such as "/dev/tty"

func GetVerboseLevel

func GetVerboseLevel() int

func InDebugMode

func InDebugMode() bool

InDebugMode returns if:

• debugger attached
• a debug build
• SetDebugMode(true) called.

To find the parent process is dlv (that is, detecting a real debugger present), another library needed.

func InDebugging

func InDebugging() bool

InDebugging returns status if debugger attached or is a debug build.

To enable the debugger attached mode for cmdr, run `go build` with `-tags=delve` options. eg:

go run -tags=delve ./cli
go build -tags=delve -o my-app ./cli

For Goland, you can enable this under 'Run/Debug Configurations', by adding the following into 'Go tool arguments:'

-tags=delve

InDebugging() is a synonym to DebuggerAttached().

NOTE that `isdelve` algor is from https://stackoverflow.com/questions/47879070/how-can-i-see-if-the-goland-debugger-is-running-in-the-program

To check wildly like cli app debug mode (via --debug), call InDebugMode.

To find the parent process is dlv (that is, detecting a real debugger present), another library needed.

func InDevelopingTime

func InDevelopingTime() (status bool)

InDevelopingTime detects whether is in developing time (debugging or testing).

If the main program has been built as an executable binary, we would assume which is not in developing time.

If GetDebugMode() is true, that's in developing time too.

func InDocker

func InDocker() bool

InDocker detects if the service is running under docker environment.

We tests these two conditions:

1. find if `/.dockerenv` exists or not.
2. `docker` in buildtags

func InDockerEnvSimple

func InDockerEnvSimple() (status bool)

InDockerEnvSimple detects whether is running within docker container environment.

InDockerEnvSimple finds if `/.dockerenv` exists or not.

func InIstio

func InIstio() bool

InIstio detects if the service is running under istio injected.

### IMPORTANT

To make this detector work properly, you must mount a DownwordAPI volume to your container/pod. See also:

https://kubernetes.io/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/

func InK8s

func InK8s() bool

InK8s detects if the service is running under k8s environment.

func InK8sYN

func InK8sYN() bool

InK8sYN is yet another DetectInK8s impl

func InTesting

func InTesting() bool

InTesting detects whether is running under go test mode

func InTestingT

func InTestingT(args []string) bool

InTestingT detects whether is running under 'go test' mode

func InTracing

func InTracing() bool

InTracing tests if trace.IsEnabled() or env.traceMode (cli app trace mode via --trace).

See the github.com/is/states/trace package.

func InVscodeTerminal

func InVscodeTerminal() bool

InVscodeTerminal tests if running under visual studio code integrated terminal

func IstioBuild

func IstioBuild() bool

func K8sBuild

func K8sBuild() bool

func NoColorMode

func NoColorMode() bool

func QuietModeEnabled

func QuietModeEnabled() bool

func ReadFile

func ReadFile(filename string) ([]byte, error)

ReadFile reads the file named by filename and returns the contents.

func ReadPassword

func ReadPassword() (text string, err error)

ReadPassword reads the password from stdin with safe protection

func RegisterStateGetter

func RegisterStateGetter(state string, getter func() bool)

RegisterStateGetter allows integrating your own detector into State(name) bool.

For example:

func customState() bool { reutrn ... }
is.RegisterStateGetter("custom", customState)
println(is.State("custom"))

func SetDebugLevel

func SetDebugLevel(hits int)

func SetDebugMode

func SetDebugMode(b bool)

func SetNoColorLevel

func SetNoColorLevel(hits int)

func SetNoColorMode

func SetNoColorMode(b bool)

func SetQuietLevel

func SetQuietLevel(hits int)

func SetQuietMode

func SetQuietMode(b bool)

func SetTraceLevel

func SetTraceLevel(hits int)

func SetTraceMode

func SetTraceMode(b bool)

func SetVerboseLevel

func SetVerboseLevel(hits int)

func SetVerboseMode

func SetVerboseMode(b bool)

func Signals

func Signals() signalS

Signals return a signals helper so that you can catch them, raise them.

For example:

package main

import (
  "context"
  "fmt"
  "os"
  "sync"

  "github.com/hedzr/env"
  "github.com/hedzr/go-socketlib/net"

  logz "logslog"
)

func main() {
  logz.SetLevel(logz.DebugLevel)

  server := net.NewServer(":7099")
  defer server.Close()

  ctx, cancel := context.WithCancel(context.Background())
  defer cancel()

  catcher := env.Signals().Catch()
  catcher.WithVerboseFn(func(msg string, args ...any) {
    logz.Debug(fmt.Sprintf("[verbose] %s", fmt.Sprintf(msg, args...)))
  }).WithSignalCaught(func(sig os.Signal, wg *sync.WaitGroup) {
    println()
    logz.Debug("signal caught", "sig", sig)
    if err := server.Shutdown(); err != nil {
    	logz.Error("server shutdown error", "err", err)
    }
    cancel()
  }).Wait(func(stopChan chan<- os.Signal, wgShutdown *sync.WaitGroup) {
    logz.Debug("entering looper's loop...")

    server.WithOnShutdown(func(err error) { wgShutdown.Done() })
    err := server.StartAndServe(ctx)
    if err != nil {
      logz.Fatal("server serve failed", "err", err)
    }
  })
}

func StartupByDoubleClick

func StartupByDoubleClick() bool

StartupByDoubleClick detects if windows golang executable file is running via double click or from cmd/shell terminator

func State

func State(stateName string) (state bool)

State returns a state with the given state name.

func States

func States() states.CmdrMinimal

States or Env returns a minimal environment settings for a typical CLI app.

See also states.CmdrMinimal.

func StringToBool

func StringToBool(val string, defaultVal ...bool) (ret bool)

StringToBool converts a string to boolean value.

func StripEscapes

func StripEscapes(str string) (strCleaned string)

StripEscapes removes any ansi color escaped sequences from a string

func Terminal

func Terminal(f *os.File) bool

Terminal detects if a file is a terminal device (tty)

func TerminalFd

func TerminalFd(fd uintptr) bool

TerminalFd detects if a file-descriptor is a terminal device (tty)

func ToBool

func ToBool(val any, defaultVal ...bool) (ret bool)

ToBool converts a value (int, bool, string) to boolean

func TraceMode

func TraceMode() bool

func Tracing

func Tracing() bool

func Tty

func Tty(w io.Writer) bool

Tty detects a writer if it is abstracting from a tty (console, terminal) device.

func TtyEscaped

func TtyEscaped(s string) bool

TtyEscaped detects a string if it contains ansi color escaped sequences Deprecated v0.5.3, use HasAnsiEscaped

func UpdateEnvWith

func UpdateEnvWith(env states.CmdrMinimal)

func VerboseBuild

func VerboseBuild() bool

func VerboseModeEnabled

func VerboseModeEnabled() bool