scribe

package
v2.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2024 License: Apache-2.0 Imports: 9 Imported by: 182

Documentation

Overview

Package scribe provides a set of interfaces to allow buildpack authors to control their logs on varying levels of granularity. This exposes high level logging functions with packit specific business logic baked into the logging as well as low level functionality that allows an author to build up their own functionality using atomic pieces.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	BlackColor   = NewColor(false, 0, -1)
	RedColor     = NewColor(false, 1, -1)
	GreenColor   = NewColor(false, 2, -1)
	YellowColor  = NewColor(false, 3, -1)
	BlueColor    = NewColor(false, 4, -1)
	MagentaColor = NewColor(false, 5, -1)
	CyanColor    = NewColor(false, 6, -1)
	WhiteColor   = NewColor(false, 7, -1)
	GrayColor    = NewColor(false, 244, -1)
)

A set of common text colors.

Functions

This section is empty.

Types

type Color 

type Color func(message string) string

A Color is a function that takes a string as an input and returns a string with the proper terminal graphic commands.

func NewColor 

func NewColor(bold bool, fg, bg int) Color

NewColor returns a Color function that will make text bold based on the boolean value of bold and set the text foreground and background, using fg and bg respectively, to any color in the 8 bit color space.

type Emitter 

type Emitter struct {
	// Logger is embedded and therefore delegates all of its functions to the
	// Emitter.
	Logger
}

An Emitter embeds the scribe.Logger type to provide an interface for complicated shared logging tasks.

Example 
package main

import (
	"os"

	"github.com/paketo-buildpacks/packit/v2/scribe"
)

func main() {
	emitter := scribe.NewEmitter(os.Stdout)

	emitter.Title("Title")
	emitter.Process("Process")
	emitter.Subprocess("Subprocess")
	emitter.Action("Action")
	emitter.Detail("Detail")
	emitter.Subdetail("Subdetail")
	emitter.Break()
	emitter.Title("Next line")

}

Output:

Title
  Process
    Subprocess
      Action
        Detail
          Subdetail

Next line

func NewEmitter 

func NewEmitter(output io.Writer) Emitter

NewEmitter returns an emitter that writes to the given output.

func (Emitter) BuildConfiguration added in v2.4.0 

func (e Emitter) BuildConfiguration(envVars map[string]string)

BuildConfiguration takes a map representing environment variables that will configure a buildpack build and prints them in a formatted table.

func (Emitter) Candidates 

func (e Emitter) Candidates(entries []packit.BuildpackPlanEntry)

Candidates takes a priority sorted list of buildpack plan entries and prints out a formatted table in priority order removing any duplicate entries.

Example 
emitter := scribe.NewEmitter(os.Stdout)

emitter.Candidates([]packit.BuildpackPlanEntry{
	{
		Metadata: map[string]interface{}{
			"version-source": "some-source",
			"version":        "some-version",
		},
	},
	{
		Metadata: map[string]interface{}{
			"version": "other-version",
		},
	},
})

Output:

    Candidate version sources (in priority order):
      some-source -> "some-version"
      <unknown>   -> "other-version"

func (Emitter) EnvironmentVariables 

func (e Emitter) EnvironmentVariables(layer packit.Layer)

EnvironmentVariables takes a layer and prints out a formatted table of the build and launch time environment variables set in the layer.

Example 
emitter := scribe.NewEmitter(os.Stdout)

emitter.EnvironmentVariables(packit.Layer{
	BuildEnv: packit.Environment{
		"NODE_HOME.default":    "/some/path",
		"NODE_ENV.default":     "some-env",
		"NODE_VERBOSE.default": "some-bool",
	},
	LaunchEnv: packit.Environment{
		"NODE_HOME.default":    "/some/path",
		"NODE_ENV.default":     "another-env",
		"NODE_VERBOSE.default": "another-bool",
	},
	SharedEnv: packit.Environment{
		"SHARED_ENV.default": "shared-env",
	},
})

Output:

  Configuring build environment
    NODE_ENV     -> "some-env"
    NODE_HOME    -> "/some/path"
    NODE_VERBOSE -> "some-bool"
    SHARED_ENV   -> "shared-env"

  Configuring launch environment
    NODE_ENV     -> "another-env"
    NODE_HOME    -> "/some/path"
    NODE_VERBOSE -> "another-bool"
    SHARED_ENV   -> "shared-env"

func (Emitter) FormattingSBOM added in v2.1.0 

func (e Emitter) FormattingSBOM(formats ...string)

FormattingSBOM takes a list of SBOM formats and logs that an SBOM is generated in each format. Note: Only logs when the emitter is in DEBUG mode.

func (Emitter) GeneratingSBOM added in v2.1.0 

func (e Emitter) GeneratingSBOM(path string)

GeneratingSBOM takes a path to a directory and logs that an SBOM is being generated for that directory.

func (Emitter) LaunchDirectProcesses added in v2.11.0 

func (e Emitter) LaunchDirectProcesses(processes []packit.DirectProcess, processEnvs ...map[string]packit.Environment)

LaunchDirectProcesses take a list of direct processes and a map of process specific enivronment varables and prints out a formatted table including the type name, whether or not it is a default process, the command, arguments, and any process specific environment variables.

func (Emitter) LaunchProcesses 

func (e Emitter) LaunchProcesses(processes []packit.Process, processEnvs ...map[string]packit.Environment)

LaunchProcesses take a list of (indirect) processes and a map of process specific enivronment varables and prints out a formatted table including the type name, whether or not it is a default process, the command, arguments, and any process specific environment variables.

Example 
emitter := scribe.NewEmitter(os.Stdout)

processes := []packit.Process{
	{
		Type:    "some-type",
		Command: "some-command",
	},
	{
		Type:    "web",
		Command: "web-command",
		Default: true,
	},
	{
		Type:    "some-other-type",
		Command: "some-other-command",
		Args:    []string{"some", "args"},
	},
}

processEnvs := []map[string]packit.Environment{
	{
		"web": packit.Environment{
			"WEB_VAR.default": "some-env",
		},
	},
	{
		"web": packit.Environment{
			"ANOTHER_WEB_VAR.default": "another-env",
		},
	},
}

emitter.LaunchProcesses(processes)
emitter.LaunchProcesses(processes, processEnvs...)

Output:

  Assigning launch processes:
    some-type:       some-command
    web (default):   web-command
    some-other-type: some-other-command some args

  Assigning launch processes:
    some-type:       some-command
    web (default):   web-command
      ANOTHER_WEB_VAR -> "another-env"
      WEB_VAR         -> "some-env"
    some-other-type: some-other-command some args

func (Emitter) LayerFlags added in v2.4.0 

func (e Emitter) LayerFlags(layer packit.Layer)

LayerFlags takes a layer and prints out the state of the build, launch, and cache layer flags in human-readable language.

func (Emitter) SelectedDependency 

func (e Emitter) SelectedDependency(entry packit.BuildpackPlanEntry, dependency postal.Dependency, now time.Time)

SelectedDependency takes in a buildpack plan entry, a postal dependency, and the current time, and prints out a message giving the name and version of the dependency as well as the source of the request for that given dependency, it will also print a deprecation warning and an EOL warning based if the given dependency is set to be deprecated within the next 30 or is past that window.

Example 
emitter := scribe.NewEmitter(os.Stdout)

deprecationDate, err := time.Parse(time.RFC3339, "2021-04-01T00:00:00Z")
if err != nil {
	log.Fatal(err)
}

entry := packit.BuildpackPlanEntry{
	Metadata: map[string]interface{}{"version-source": "some-source"},
}

dependency := postal.Dependency{
	Name:            "Some Dependency",
	Version:         "some-version",
	DeprecationDate: deprecationDate,
}

emitter.Title("SelectedDependency")
emitter.SelectedDependency(entry, dependency, deprecationDate.Add(-30*24*time.Hour))
emitter.SelectedDependency(entry, dependency, deprecationDate.Add(-29*24*time.Hour))
emitter.SelectedDependency(entry, dependency, deprecationDate.Add(24*time.Hour))

Output:

SelectedDependency
    Selected Some Dependency version (using some-source): some-version

    Selected Some Dependency version (using some-source): some-version
      Version some-version of Some Dependency will be deprecated after 2021-04-01.
      Migrate your application to a supported version of Some Dependency before this time.

    Selected Some Dependency version (using some-source): some-version
      Version some-version of Some Dependency is deprecated.
      Migrate your application to a supported version of Some Dependency.

func (Emitter) WithLevel added in v2.0.2 

func (e Emitter) WithLevel(level string) Emitter

WithLevel takes in a log level string and configures the underlying Logger log level. To enable debug logging the log level must be set to "DEBUG".

type FormattedList 

type FormattedList []string

A FormattedList is a wrapper for []string to extend functionality.

Example 
package main

import (
	"fmt"

	"github.com/paketo-buildpacks/packit/v2/scribe"
)

func main() {
	fmt.Println(scribe.FormattedList{
		"third",
		"first",
		"second",
	}.String())

}

Output:

first
second
third

func (FormattedList) String 

func (l FormattedList) String() string

Sorts the FormattedList alphabetically and then prints each item on its own line.

type FormattedMap 

type FormattedMap map[string]interface{}

A FormattedMap is a wrapper for map[string]interface{} to extend functionality.

Example 
package main

import (
	"fmt"

	"github.com/paketo-buildpacks/packit/v2/scribe"
)

func main() {
	fmt.Println(scribe.FormattedMap{
		"third":  3,
		"first":  1,
		"second": 2,
	}.String())

}

Output:

first  -> "1"
second -> "2"
third  -> "3"

func NewFormattedMapFromEnvironment 

func NewFormattedMapFromEnvironment(environment map[string]string) FormattedMap

NewFormattedMapFromEnvironment take an environment and returns a FormattedMap with the appropriate environment variable information added.

Example 
fmt.Println(scribe.NewFormattedMapFromEnvironment(packit.Environment{
	"OVERRIDE.override": "some-value",
	"DEFAULT.default":   "some-value",
	"PREPEND.prepend":   "some-value",
	"PREPEND.delim":     ":",
	"APPEND.append":     "some-value",
	"APPEND.delim":      ":",
}).String())

Output:

APPEND   -> "$APPEND:some-value"
DEFAULT  -> "some-value"
OVERRIDE -> "some-value"
PREPEND  -> "some-value:$PREPEND"

func (FormattedMap) String 

func (m FormattedMap) String() string

Sorts all of the keys in the FormattedMap alphabetically and then constructs a padded table.

type LeveledLogger 

type LeveledLogger struct {
	TitleWriter      io.Writer
	ProcessWriter    io.Writer
	SubprocessWriter io.Writer
	ActionWriter     io.Writer
	DetailWriter     io.Writer
	SubdetailWriter  io.Writer
}

A LeveledLogger provides a standard interface for basic formatted logging.

func NewLeveledLogger 

func NewLeveledLogger(writer io.Writer) LeveledLogger

NewLeveledLogger takes a writer and returns a LeveledLogger that writes to the given writer.

func (LeveledLogger) Action 

func (l LeveledLogger) Action(format string, v ...interface{})

Action takes a string and optional formatting, and prints a formatted string with three levels of indentation.

func (LeveledLogger) Break 

func (l LeveledLogger) Break()

Break inserts a line break in the log output

func (LeveledLogger) Detail 

func (l LeveledLogger) Detail(format string, v ...interface{})

Detail takes a string and optional formatting, and prints a formatted string with four levels of indentation.

func (LeveledLogger) Process 

func (l LeveledLogger) Process(format string, v ...interface{})

Process takes a string and optional formatting, and prints a formatted string with one level of indentation.

func (LeveledLogger) Subdetail 

func (l LeveledLogger) Subdetail(format string, v ...interface{})

Subdetail takes a string and optional formatting, and prints a formatted string with five levels of indentation.

func (LeveledLogger) Subprocess 

func (l LeveledLogger) Subprocess(format string, v ...interface{})

Subprocess takes a string and optional formatting, and prints a formatted string with two levels of indentation.

func (LeveledLogger) Title 

func (l LeveledLogger) Title(format string, v ...interface{})

Title takes a string and optional formatting, and prints a formatted string with zero levels of indentation.

type Logger 

type Logger struct {
	LeveledLogger
	Debug LeveledLogger
	// contains filtered or unexported fields
}

A Logger provides a standard logging interface for doing basic low level logging tasks as well as debug logging.

Example 
package main

import (
	"os"

	"github.com/paketo-buildpacks/packit/v2/scribe"
)

func main() {
	logger := scribe.NewLogger(os.Stdout)

	logger.Title("Title")
	logger.Process("Process")
	logger.Subprocess("Subprocess")
	logger.Action("Action")
	logger.Detail("Detail")
	logger.Subdetail("Subdetail")
	logger.Break()
	logger.Title("Next line")

}

Output:

Title
  Process
    Subprocess
      Action
        Detail
          Subdetail

Next line

func NewLogger 

func NewLogger(writer io.Writer) Logger

NewLogger takes a writer and returns a Logger that writes to the given writer. The default writter sends all debug logging to io.Discard.

func (Logger) WithLevel 

func (l Logger) WithLevel(level string) Logger

WithLevel takes in a log level string and configures the log level of the logger. To enable debug logging the log level must be set to "DEBUG".

Example 
package main

import (
	"os"

	"github.com/paketo-buildpacks/packit/v2/scribe"
)

func main() {
	logger := scribe.NewLogger(os.Stdout)

	logger.Title("First line")
	logger.Debug.Title("Debug line")
	logger.Title("Next line")
	logger.Break()

	logger = logger.WithLevel("DEBUG")

	logger.Title("First line")
	logger.Debug.Title("Debug line")
	logger.Title("Next line")

}

Output:

First line
Next line

First line
Debug line
Next line

type Option 

type Option func(Writer) Writer

An Option is a way to configure a writer's format.

func WithColor 

func WithColor(color Color) Option

WithColor takes a Color and returns an Option which can be passed in while creating a new Writer to configure the color of the output of the Writer.

func WithIndent 

func WithIndent(indent int) Option

WithIndent takes an indent level and returns an Option which can be passed in while creating a new Writer to configure the indentation level of the output of the Writer.

func WithPrefix added in v2.4.0 

func WithPrefix(prefix string) Option

WithPrefix takes a prefix string and returns an Option which can be passed in while creating a new Writer to configure a prefix to be prepended to the output of the Writer.

type Writer 

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

A Writer conforms to the io.Writer interface and allows for configuration of output from the writter such as the color or indentation through Options.

func NewWriter 

func NewWriter(writer io.Writer, options ...Option) *Writer

NewWriter takes a Writer and Options and returns a Writer that will format output according to the options given.

func (*Writer) Write 

func (w *Writer) Write(b []byte) (int, error)

Write takes the given byte array and formats it in accordance with the options on the writer and then outputs that formated text.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.