clicore

README

CLI Core

• A library for feature-rich, configurable, and cross-project consistent command line interfaces.

Usage

• To use clicore, just define a CommandConfig and call config.Run().

Example

• Sample main package, importing your cli:

package main
import (
	"myrepo/pkg/mycli"
)
func main() {
	mycli.MyCommandConfig.Run()
}

• Sample package, defining your CLI library and exporting the CommandConfig:

package mycli

import "github.com/solo-io/go-utils/clicore"

var MyCommandConfig = clicore.CommandConfig{
	Command:             App,
	Version:             version.Version,
	FileLogPathElements: FileLogPathElements,
	OutputModeEnvVar:    OutputModeEnvVar,
	RootErrorMessage:    ErrorMessagePreamble,
	LoggingContext:      []interface{}{"version", version.Version},
}

How to write logs to the console and log file

There are three helpers that you can use:

contextutils.CliLogInfow(ctx, "this info log goes to file and console")
contextutils.CliLogWarnw(ctx, "this warn log goes to file and console")
contextutils.CliLogErrorw(ctx, "this error log goes to file and console")

Key-value pairs are supported too:

contextutils.CliLogInfow(ctx, "this infow log should go to file and console",
    "extrakey1", "val1")

Which is equivalent to the longer form:

contextutils.LoggerFrom(ctx).Infow("message going to file only",
	zap.String("cli", "info that will go to the console and file",
	"extrakey1", "val1")

Usage in tests

• clicore was designed to simplify CLI specification and testing.
• To run clicore in test mode, call cliOutput, err := cli.GlooshotConfig.RunForTest(args).
  • Output from the command (stdout, stderr, and any log files) can then be validated one by one.
• See the test file for an example

Documentation

Index

• func BuildCliLogger(pathElements []string, outputModeEnvVar string) *zap.SugaredLogger
• func BuildMockedCliLogger(pathElements []string, outputModeEnvVar string, mockTargets *MockTargets) *zap.SugaredLogger
• func ExecuteCliOutErr(ct *CliTestConfig) (string, string, error)
• func FilePathFromHomeDir(pathElementsRelativeToHome []string) (string, error)
• func NewCliEncoder(printedKey string) zapcore.Encoder
• type CliOutput
• type CliTestConfig
• type CommandConfig
  • func (cc CommandConfig) Run()
  • func (cc *CommandConfig) RunForTest(args string) (CliOutput, error)
• type MockTargets
  • func NewMockTargets() MockTargets
• type MockWriteSyncer
  • func (m *MockWriteSyncer) Summarize() (string, uint, uint)
  • func (m *MockWriteSyncer) Sync() error
  • func (m *MockWriteSyncer) Write(in []byte) (int, error)
• type RootCommandFunc

Functions

func BuildCliLogger

func BuildCliLogger(pathElements []string, outputModeEnvVar string) *zap.SugaredLogger

BuildCliLogger creates a set of loggers for use in CLI applications. - A json-formatted file logger that writes all log messages to the specified filename - A human-friendly console logger that writes info and warning messages to stdout - A human-friendly console logger that writes info and warning messages to stderr

func BuildMockedCliLogger

func BuildMockedCliLogger(pathElements []string, outputModeEnvVar string, mockTargets *MockTargets) *zap.SugaredLogger

BuildMockedCliLogger is the test-environment counterpart of BuildCliLogger It stores log output in buffers that can be inspected by tests.

func ExecuteCliOutErr

func ExecuteCliOutErr(ct *CliTestConfig) (string, string, error)

ExecuteCliOutErr is a helper for calling a cobra command within a test

func FilePathFromHomeDir

func FilePathFromHomeDir(pathElementsRelativeToHome []string) (string, error)

FilePathFromHomeDir is a utility that makes it easier to find the absolute path to a file, given its file path elements relative to its home directory. pathElementsRelativeToHome is passed as an array to avoid os-specific directory delimiter complications example: []string{".config","default.yaml"}

func NewCliEncoder

func NewCliEncoder(printedKey string) zapcore.Encoder

Types

type CliOutput

type CliOutput struct {
	LoggerConsoleStderr string
	LoggerConsoleStout  string
	LoggerFileContent   string
	CobraStderr         string
	CobraStdout         string
}

CliOutput captures all the relevant output from a Cobra Command For clarity and simplicity, output from zapcore loggers are stored separately otherwise, it would be necessary to coordinate the initialization of the loggers with the os.Std*** manipulation done in ExecuteCliOutErr

type CliTestConfig

type CliTestConfig struct {
	CommandConfig *CommandConfig
	MockTargets   *MockTargets
	TestArgs      string
	// contains filtered or unexported fields
}

type CommandConfig

type CommandConfig struct {
	Args                string
	Command             RootCommandFunc
	CommandErrorHandler func(error)
	RootErrorMessage    string
	OutputModeEnvVar    string
	LoggingContext      []interface{}
	FileLogPathElements []string
	Version             string
	// contains filtered or unexported fields
}

func (CommandConfig) Run

func (cc CommandConfig) Run()

func (*CommandConfig) RunForTest

func (cc *CommandConfig) RunForTest(args string) (CliOutput, error)

type MockTargets

type MockTargets struct {
	Stdout  *MockWriteSyncer
	Stderr  *MockWriteSyncer
	FileLog *MockWriteSyncer
}

func NewMockTargets

func NewMockTargets() MockTargets

type MockWriteSyncer

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

func (*MockWriteSyncer) Summarize

func (m *MockWriteSyncer) Summarize() (string, uint, uint)

func (*MockWriteSyncer) Sync

func (m *MockWriteSyncer) Sync() error

func (*MockWriteSyncer) Write

func (m *MockWriteSyncer) Write(in []byte) (int, error)

type RootCommandFunc

type RootCommandFunc func(ctx context.Context, version string) (rootCmd *cobra.Command)