Skip to content
master
Switch branches/tags
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
img
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Box CLI Maker 📦

Box CLI Maker is a Highly Customized Terminal Box Creator.

go.dev reference godocs.io CI Go Report Card GolangCI GitHub release Mentioned in Awesome Go

Features

  • Make Terminal Box in 8️⃣ inbuilt different styles
  • 16 Inbuilt Colors and True Color Support 🎨
  • Custom Title Positions
  • Make your own Terminal Box style 📦
  • Align the text according to the need
  • Unicode, Emoji and Windows Console Support 😋
  • Written in 🇬 🇴

Installation

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

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) accepts a Config struct with following parameters and returns a Box struct.

  • Parameters
    • Px : Horizontal Padding
    • Py : Vertical Padding
    • ContentAlign : Align the content inside the Box i.e. Center, Left and Right
    • Type: Type of Box
    • TitlePos : Position of the Title i.e. Inside, Top and Bottom
    • Color : Color of the Box

Box struct Methods

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

  • Parameters
    • title : Title of the Box
    • lines : Content to be written inside the Box

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

  • Parameters
    • title : Title of the Box
    • lines : Content to be written inside the Box

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

  • Parameters
    • title : Title of the Box
    • lines : Content to be written inside the Box

Box Types

  • Single

single

  • Single Double

single_double

  • Double

double

  • Double Single

double_single

  • Bold

bold

  • Round

round

  • Hidden

hidden

  • Classic

classic

Title Positions

  • Inside

single

  • Top

top

  • Bottom

bottom

Making custom Box

You can make your custom Box by using the inbuilt Box struct provided by the module.

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

Using it:

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")
}

Output:

custom

Color Types

It has color support from gookit/color module from which this module 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 Color option is empty or invalid then Box with default Color is formed.

  1. True Color is also possible though you need to provide it as uint or [3]uint and make sure that the terminals which will be targetted must have it supported.

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

As convenience, if the terminal's doesn't support True Color then it will round off according to the terminal's max supported colors which makes it easier for the users not to worry about other terminal for most of the 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 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 it is supported by all terminals now.

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

Note

1. Vertical Alignment

As different terminals have different font by default so 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 know terminal emulators which can render Unicode and Emojis properly on Windows.
  • Indic Text only works on very few Terminals as less support it.
  • 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 Set is used which becomes problematic for finding the length as the font changes during runtime.
  • Change your font which supports Unicode and Emojis else the right vertical alignment will break.

3. Terminal Color Detection

It is possible to round off true color provided to 8 bit or 16 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 this can be fixed for your terminal then you can always make a PR.

The following two points are just applicable for Unix systems:

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

  • If you are targetting 8 bit color based terminals and the module couln't detect it then set your environment variable TERM to name of the terminal emulator with 256color as suffix like xterm-256color.

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

In Online Playgrounds, CI/CDs, Browsers etc, it is recommended not to use this module with color effect as few may have it but this is hard to detect in general. If you think that it's possible then open an issue and address the solution!

Acknowledgements

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

Special thanks to @elimsteve who helped me to optimize the code and told me the best possible ways to fix my problems and @JalonSolov for tab lines support.

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

Related

License

Licensed under MIT