box

README

---

---

Features

• Make a Terminal Box in 8️⃣ inbuilt different styles
• 16 Inbuilt Colors and True Color Support 🎨
• Custom Title Positions 📏
• Make your Terminal Box style 📦
• Support for ANSI, Tabbed, Multi-line and Line Wrapping boxes 📑
• Align the text according to your needs 📐
• Unicode, Emoji and Windows Console Support 😋
• Written in 🇬 🇴

Installation

 go get github.com/Delta456/box-cli-maker/v2

Usage

In main.go

package main

import "github.com/Delta456/box-cli-maker/v2"

func main() {
 Box := box.New(box.Config{Px: 2, Py: 5, Type: "Single", Color: "Cyan"})
 Box.Print("Box CLI Maker", "Highly Customized Terminal Box Maker")
}

box.New(config Config) takes Box Config and returns a Box from the given Config.

• Parameters
  • Px : Horizontal Padding
  • Py : Vertical Padding
  • ContentAlign : Content Alignment inside Box i.e. Center, Left and Right
  • Type: Box Type
  • TitlePos : Title Position of Box i.e. Inside, Top and Bottom
  • Color : Box Color
  • TitleColor : Title Color
  • ContentColor : Content Color
  • AllowWrapping: Flag to allow custom Content wrapping
  • WrappingLimit: Wrap the Content up to the Limit

Box Methods

Box.Print(title, lines string) prints Box from the specified arguments.

• Parameters
  • title : Box Title
  • lines : Box Content

Box.Println(title, lines string) prints Box in a newline from the specified arguments.

• Parameters
  • title : Box Title
  • lines : Box Content

Box.String(title, lines string) string returns string representation of Box.

• Parameters
  • title : Box Title
  • lines : Box Content

Box Types

• Single

• Single Double

• Double

• Double Single

• Bold

• Round

• Hidden

• Classic

Title Positions

• Inside

• Top

• Bottom

Custom Box

A Custom Box can be created by using the built-in Box struct provided by the module.

type Box struct {
  TopRight    string // TopRight Corner Symbols
  TopLeft     string // TopLeft Corner Symbols
  Vertical    string // Vertical Bar Symbols
  BottomRight string // BottomRight Corner Symbols
  BottomLeft  string // BottomLeft Corner Symbols
  Horizontal  string // Horizontal Bar Symbols
  Config             // Box Config
}

Usage

In main.go:

package main

import "github.com/Delta456/box-cli-maker/v2"

func main() {
    config := box.Config{Px: 2, Py: 3, Type: "", TitlePos: "Inside"}
    boxNew := box.Box{TopRight: "*", TopLeft: "*", BottomRight: "*", BottomLeft: "*", Horizontal: "-", Vertical: "|", Config: config}
    boxNew.Println("Box CLI Maker", "Make Highly Customized Terminal Boxes")
}

More examples can be found in the examples/ folder.

Color Types

Color support is provided by the gookit/color module from which it uses FgColor and FgHiColor. Color is a key for the following maps:

 fgColors map[string]color.Color = {
  "Black":   color.FgBlack,
  "Blue":    color.FgBlue,
  "Red":     color.FgRed,
  "Green":   color.FgGreen,
  "Yellow":  color.FgYellow,
  "Cyan":    color.FgCyan,
  "Magenta": color.FgMagenta,
  "White":   color.FgWhite,
}

 fgHiColors map[string]color.Color = {
  "HiBlack":   color.FgDarkGray,
  "HiBlue":    color.FgLightBlue,
  "HiRed":     color.FgLightRed,
  "HiGreen":   color.FgLightGreen,
  "HiYellow":  color.FgLightYellow,
  "HiCyan":    color.FgLightCyan,
  "HiMagenta": color.FgLightMagenta,
  "HiWhite":   color.FgLightWhite,
}

If you want High-Intensity Colors then the Color name must start with Hi. If the Color option is empty or invalid then no colour is applied.

1. True Color is also possible though you need to provide it either as uint or [3]uint.

2. [3]uint's elements all must be in a range of [0, 0xFF] and uint in range of [0x000000, 0xFFFFFF].

As a convenience, if the terminal doesn't support True Color then it will round off according to the terminal's max supported colours which makes it easier for the users not to worry about other terminals in most cases.

Here's a list of 24-bit supported terminals and 8 bit supported terminals.

This module also enables True Color and 256 Colors support on Windows Console through Virtual Terminal Processing but you need to have at least Windows 10 Version 1511 for 256 colors or Windows 10 Version 1607 for True Color Support.

4-bit Colors are now standardized so they should be supported by all Terminals now.

If ConEmu or ANSICON is installed for Windows systems then it will also be detected. It is highly recommended to use the latest versions of both of them to have the best experience.

Content Wrapping

This library allows the usage of custom wrapping of Content so that the Box formed will be created according to your own needs.

To enable this Config.AllowWrapping must be set to true plus you can also provide your own wrapping limit via Config.WrappingLimit which has a default value of 2*TermWidth/3 where TermWidth is the current terminal's width.

Note

1. Vertical Alignment

As different terminals have different fonts by default, the right vertical alignment may not be aligned well. You will have to change your font accordingly to make it work.

2. Limitations of Unicode and Emoji

It uses mattn/go-runewidth for Unicode and Emoji support though there are some limitations:

• Windows Terminal, ConEmu and Mintty are the only known terminal emulators which can render Unicode and Emojis properly on Windows.
• Indic Text only works on very few Terminals.
• It is recommended not to use this for Online Playgrounds like Go Playground and Repl.it, CI/CDs etc. because they use a font that only has ASCII support and other Character Sets are used, which becomes problematic for finding the length as the font changes at runtime.
• Some changes may be needed to your font which supports Unicode and Emojis else the right vertical alignment may likely break.

3. Terminal Color Detection

It is possible to round off True Color provided to 8-bit or 4-bit according to your terminal's maximum capacity.

There is no standardized way of detecting the terminal's maximum color capacity so the way of detecting your terminal might not work for you. If you have a fix for your terminal then you can always make a PR.

The following two points are only applicable for Unix systems:

• If the module can't detect the True Color of the terminal then your environment variable COLORTERM must be changed to truecolor or 24bit for True Color support.

• If Targetting 8-bit color-based terminals and the module couldn't detect it, then the environment variable TERM must be set to the name of the terminal emulator with 256color as a suffix like xterm-256color.

There might be no color effect for very old terminals like Windows Console (Legacy Mode) or TERM environment variable which gives DUMB so the module will output some garbage value or a warning if used.

It is not recommended to use this module with color effect in Online Playgrounds, CI/CD, Browsers etc, as few may support color and this is hard to detect in general. If there is a possible way, then open an issue and address the solution!

4. Tabs

This library supports the usage of tabs but their use should be limited.

Projects using Box CLI Maker

• kubernetes/minikube: Run Kubernetes locally.
• +Many More!

Acknowledgements

I thank the following people and their packages whom I have studied and was able to port to Go accordingly.

• thecodrr/boxx
• Atrox/box
• sindreorhus-cli-boxes

Also special thanks to @elimsteve who helped me to optimize the code and told me the best possible ways to fix my problems, @JalonSolov for tab lines support and Kunal Raghav for making the library's logo.

Kudos to moul/golang-repo-template for their Go template.

License

Licensed under MIT

Documentation

Overview

Package box a.k.a Box CLI Maker is a Highly Customized Terminal Box Creator written in Go.

It provides many styles and options to make Boxes. There are 8 inbuilt styles and has Color support via RGB uint, RGB Array of [3]uint and string (Given).

Inbuilt Box Styles: Single, Double, Bold, Single Double, Double Single, Round, Hidden and Classic

Inbuilt Colors: Black, Blue, Red, Yellow, Green, Cyan, Magenta, White, HiBlack, HiBlue, HiRed, HiYellow, HiGreen, HiCyan, HiMagenta and HiWhite

It also has Unicode and Emoji support which works across almost all terminals. Unlike other CLI Makers, Box CLI Maker also supports tab, multi-line strings and string wrapping.

Disclaimer: As different terminals have different fonts by default so the right vertical alignment may not be aligned well. You will have to change your font accordingly to make it work.

Basic Example:

Box := box.New(box.Config{Px: 2, Py: 5, Type: "Single", Color: "Cyan"})
Box.Print("Box CLI Maker", "Highly Customized Terminal Box Maker")

You can specify and change the options by changing the below Config struct.

Box := box.New(box.Config{Px: 2, Py: 5, Type: "Single", TitlePos: "Top", ContentAlign: "Left"})

TitlePos can be changed to Inside, Top, Bottom and ContentAlign to be Left, Right and Center. By default TitlePos is Inside, ContentAlign is Left and Style is Single.

Manual string wrapping is also allowed via a flag Config.AllowWrapping, by the default padding, is 2*TermWidth/3.

String() method can be for the string representation of the Box.

Box := box.New(box.Config{Px: 2, Py: 5, Type: "Single", Color: "Cyan"})
boxStr := Box.String("Box CLI Maker", "Highly Customized Terminal Box Maker")

True Color is also supported and it can be by providing an array of [3]uint or uint.

There might be some terminals not supporting True Color so in this case, it will detect the terminal's max color capacity then will round off True Color to either 4-bit or 8-bit respectively.

Title and Content can also be colored by passing the colors needed to the fields box.TitleColor and box.ContentColor respectively.

This module also enables True Color and 256 Colors support on Windows Console but you need have at least Windows 10 Version 1511 for 256 colors or Windows 10 Version 1607 for True Color Support.

Example of True Color via uint:

Box := box.New(box.Config{Px: 2, Py: 5, Type: "Single", Color: uint(0x34562f)})
Box.Println("Box CLI Maker", "Highly Customized Terminal Box Maker")

Note: uint must be in a range of [0x000000, 0xFFFFFF].

Example of True Color via [3]uint:

Box := box.New(box.Config{Px: 2, Py: 5, Type: "Single", Color: [3]uint{23, 56, 78}})
Box.Println("Box CLI Maker", "Highly Customized Terminal Box Maker")

Note: [3]uint array elements must be in a range of [0x0, 0xFF].

Custom Box Style can also be by using box.Box:

config := box.Config{Px: 2, Py: 3, Type: "", TitlePos: "Inside"}
boxNew := box.Box{TopRight: "*", TopLeft: "*", BottomRight: "*", BottomLeft: "*", Horizontal: "-", Vertical: "|", Config: config}

More info and examples can be found in README.md and examples/ folder

Index

• type Box
  • func New(config Config) Box
  • func (b Box) Print(title, lines string)
  • func (b Box) Println(title, lines string)
  • func (b Box) Sprintf(title, lines string) string
  • func (b Box) String(title, lines string) string
• type Config

Types

type Box

type Box struct {
	TopRight    string // TopRight Corner Symbols
	TopLeft     string // TopLeft Corner Symbols
	Vertical    string // Vertical Bar Symbols
	BottomRight string // BottomRight Corner Symbols
	BottomLeft  string // BottomLeft Corner Symbols
	Horizontal  string // Horizontal Bars Symbols
	Config             // Box Config
}

Box defines the design

func New

func New(config Config) Box

New takes Box Config and returns a Box from the given Config

func (Box) Print

func (b Box) Print(title, lines string)

Print prints the Box

func (Box) Println

func (b Box) Println(title, lines string)

Println adds a newline before and after printing the Box

func (Box) Sprintf

func (b Box) Sprintf(title, lines string) string

Output the string of the Box print

func (Box) String

func (b Box) String(title, lines string) string

String returns the string representation of Box

type Config

type Config struct {
	Py            int         // Horizontal Padding
	Px            int         // Vertical Padding
	ContentAlign  string      // Content Alignment inside Box
	Type          string      // Box Type
	TitlePos      string      // Title Position
	TitleColor    interface{} // Title Color
	ContentColor  interface{} // Content Color
	Color         interface{} // Box Color
	AllowWrapping bool        // Flag to allow custom Content Wrapping
	WrappingLimit int         // Wrap the Content upto the Limit
}

Config is the configuration needed for the Box to be designed