clifmt/README.md

| extended terminal format |

Simple utility written in go that extends the standard fmt.Sprintf and fmt.Printf functions. It allows you to set foreground/background color, bold, underlined, italic text and hyperlinks.

• I. How to use
  • 1) Requirements
  • 2) Installation
  • 3) Usage
    • a) As a library
    • b) As an executable
• II. Format syntax
  • 1) Text style
• III. Animations
• IV. Screenshots
  • Colorizing format example :
  • Markdown-like format example
• V. Incoming features

---

I. How to use

1) Requirements

The package clifmt can be used as a go library or as an executable. In either case, you need :

• any recent linux system (has not been tested over other OSes)
• go installed (has not been tested under version 1.11)

2) Installation

Simply launch the following command in your favorite terminal

$ go get -u git.xdrm.io/go/clifmt

It will download the project sources into $GOPATH/src/git.xdrm.io/go/clifmt.

3) Usage

a) As a library

You must import the library into your program with

import "git.xdrm.io/go/clifmt"

Then, the following methods will be available

// Printf wraps the standard fmt.Printf() features but adds formatting capabilities
func Printf(fmt string, args ...interface{}) error

// Sprintf acts as 'Printf' but returns the string instead of printing it
func Sprintf(fmt string, args ...interface{}) (string, error)

// Printpf acts as 'Printf' but takes as arguments either standard fmt.Printf arguments, or channels that will update the output when provided with correct values.
func Printpf(fmt string, args ...interface{}) (error)

b) As an executable

You must run from your terminal

$ go get -u git.xdrm.io/go/clifmt/cmd/clifmt

The clifmt executable will be available in your $GOBIN directory.

WARNING: The executable tool is a Work In Progress, it is not stable for now. You can use clifmt --help anyway to see details on the format, coloring, etc.

---

II. Format syntax

1) Text style

The format has been designed with the markdown syntax in mind, but has some differences due to implementation issues and for stability.

The format is better described by the sample below than explanations :

// markdown-like
Printf("some normal text")
Printf("**some bold text**")
Printf("*some italic text*")
Printf("_some underline text_")
Printf("[link label](http://link_url)")

// colors
Printf("${red text}(red)")
Printf("${red text over blue background}(red:blue)")
Printf("${blue background text}(:blue)")

The code below will print the following result :

Any syntax feature (e.g. bold, color, hyperlink, ...) can be included in any other. In the same way any syntax feature can be interlaced (e.g. "startA startB stopA stopB") with each other.

Note that there can be some issues with interlaced hyperlinks as it is supported as other syntax features. But it works perfectly when used alone.

Color names (e.g. red, blue) can be replaced by their hexadecimal representation (e.g. #ff0000, #0000ff) or the short version (e.g. #f00, #00f).

---

III. Animations

The Printpf method allows you to pass channels among ordinary arguments. It allows you to animate the text you want to print each time you send data on a channel argument.

The example below shows a simple progress bar using markdown-like syntax, colors and animations :

package main

import (
	"git.xdrm.io/go/clifmt"
	"time"
)

func main() {
    // (1) animated values
	var (
		status   = make(chan interface{})
		color    = make(chan interface{})
		progress = make(chan interface{})
	)

    // (2) print your animated values
	go clifmt.Printpf("[${%s}(%s)] **%d**%%", status, color, progress)

    // (3) animate values
	status <- "download"
	color <- "red"
	for i := 0; i < 100; i++ {
		progress <- i
		time.Sleep(time.Millisecond * 200)
	}
	status <- "done"
	color <- "green"
}

The result is the following :

---

IV. Screenshots

Colorizing format example :

Markdown-like format example

---

V. Incoming features

• markdown-like formatting - bold, italic, underlined, (strike-through?)
• command-line executable - align text from terminal
• global alignment - align text dynamically
• progress-line - redrawing format to show, for instance an animated progress bar on the same line