easyft-logger v0.1.3

Easy FT Logger

Easy FT Logger (FT means Formatted Text) is a very simple JavaScript console logger for node.js that offers an intelligible syntax, merely named Easy FT, as a substitute for the ANSI escape code.

The Easy FT syntax is an explicit style declaration, or set of declarations, that is easy to memorize and makes sense for any basic English-speaker, unlike the ANSI Escape Code which may certainly be almost always shorter, but which is a bunch of integers, and semicolons, that makes sense only for those who learnt it by heart.

Easy FT allows the extension of its features, either for a specific logger, or for all the loggers, which implies that it can be used beyond the AINSI escape code substitution.

Using Easy FT Logger

The Easy FT Logger module exports a class whith static and instance attributes and methods. Therefore, to log some stuffs, an EasyFTLogger object must be instanciated:

const EasyFTLogger = require("easyft-logger");
const logger = new EasyFTLogger();

The instanciated logger will copy all default values of EasyFTLogger: specials, styles and the converters.

Then the EasyFTLogger object can be used to log anything:

logger.log("%{bold}Today%{} is a %{italic; orange}sunny%{} day!");
// OR
logger.log("%{bold}%s%{} %s %{italic; orange}%s%{} %s",
		   "Today", "is a", "sunny", "day!");

Output:

Today is a sunny day!

*The specified colors (that use HTML) in the documentation are not displayed in npm or github*

Log

The log functions formats the message to replace Easy FT statements and uses the corresponding methods of the JavaScript console:

• log(message[, ...args])
• info(message[, ...args])
• warn(message[, ...args])
• error(message[, ...args])

It is also possible to pass an array with the message and arguments to the functions prefixed with $:

• $log(messageAndArgs)
• $info(messageAndArgs)
• $warn(messageAndArgs)
• $error(messageAndArgs)

Special Characters

The EasyFTLogger class and instance contain a specials attribute which is an object. The names are the charater(s) between brackets. They must be declared in lower-case and cannot use the } character. The values are the values that replace the corresponding statements in a message.

By default, there is only one special character:

Styles

The EasyFTLogger class and instance contain a styles attribute which is an object that gives a specific name to a specific style of the ANSI escape code.

• The names in the object are the names of the style (like red or bold), they must be declared in lower-case and cannot contain the } character.
• The values is the ANSI escape code that replaces the given Easy FT statement.

There are two differences between a style and a special character:

• The style can only generate an ANSI escape code. Indeed, Easy FT will surround the result with \x1b[ and m (For example, in the styles, red refers to 38;2;255;0;0 and logging %{red} sends \x1b[38;2;255;0;0m to the console)
• The syntax allows multiples styles separated with semicolons and optional whitespaces in one statements (%{bold; red}).

Styles: Reset

Writing nothing is the same as 0, r or reset and resets the style: %{}, %{0}, %{r} and %{reset} return the same.

Easy FT does not reset anything automatically, so it is better always to reset the style at the end of a message if it is required, otherwise, further usages of the console may output the text with the last defined style.

Styles: ANSI escape code

The Easy FT style statement also allows to use ANSI escape codes. In general, every integers is returned as it is: %{bold; 38;2; 255; 200; 50} -> \x1b[1;38;2;255;200;50m. Using or not the ANSI escape code depends whether or not the code required to be read by other developpers that may not know the ANSI escape code.

Styles: Text

The convention for text style is to use a name and add a shortcut with only one letter. Here is the list of the default styles:

Styles: Defined Colors

Easy FT Logger uses RGB values to define the default colors. The result depends on the shell and it may diverge from the display of the documentation. (*The specified colors - that use HTML - in the documentation are not displayed in npm or github*). However you can use the static or instance printColors method to see the colors.

Styles: Defined Colors - Background and Text:

Each color has a background version with the bg: prefix and a text version using the c: prefix or no prefix at all.

This prefix system is only a convention and Easy FT defines all the style in the same way. However, the addColor static and instance method will automatically generate the background and text colors with the specific prefixes. See the Defining Colors chapter for deeper information.

Of course, it is possible to define together a background and a text color. For example: %{yellow; bg:red}I have no idea what the yellow on red refers to.%{}.

Output:

I have no idea what the yellow on red refers to.

*The specified colors (that use HTML) in the documentation are not displayed in npm or github*

Styles: Defined Colors - Light and Dark:

When a color exists, it often exists a light and dark version. The default colors all provide a light and a dark version. For example: it exists the red color, as well as the lightred and darkred ones.

Styles: Defined Colors - All Versions of a Color:

As a summary, here is the list of red colors:

Styles: Defined Colors - All Default Colors:

Here is the list of all the default colors offered by Easy FT Logger which contains two synonyms: grey = gray and magenta = pink.

*The specified colors (that use HTML) in the documentation are not displayed in npm or github*

Using EasyFTLogger.printColor() displays the colors as seen in the shell.

• lightwhite = white
• darkwhite
• lightgrey = lightgray
• grey = gray
• darkgrey = darkgray
• lightblack
• black = darkblack
• lightred
• red
• darkred
• lightorange
• orange
• darkorange
• lightyellow
• yellow
• darkyellow
• lightgreenyellow
• greenyellow
• darkgreenyellow
• lightgreen
• green
• darkgreen
• lightaquamarine
• aquamarine
• darkaquamarine
• lightcyan
• cyan
• darkcyan
• lightazure
• azure
• darkazure
• lightblue
• blue
• darkblue
• lightviolet
• violet
• darkviolet
• lightmagenta = lightpink
• magenta = pink
• darkmagenta = darkpink
• lightvioletred
• violetred
• darkvioletred

Styles: RGB Colors

Easy FT provides a syntax to write some rgb colors. This kind of color has nothing to do with the styles attribute, it uses a converter. See the corresponding chapter for further information.

The syntax of the declaration of an rgb color is: [bg:]rgb(r[,g[,b]])

• r, g and b are integers between 0 and 255.
• An empty parameter is set to 0: rgb(255) = rgb(255, 0, 0) and rgb(255,,50) = rgb(255, 0, 50).
• Spaces are allowed around arguments: rgb( 255, 200, 50 ).
• Further parameters are ignored: rgb(255, 0, 0, 10) = rgb(255, 0, 0).
• The bg: prefix indicates that it is a background color: bg:rgb(50, 200, 150).

Defining Colors

To know more about the syntax and usage of colors, see the Styles: Defined Colors sub-chapter of the Styles chapter.

EasyFTLogger provides a static and instance addColor method:

addColor(name:string, 
		light: integer|integer[3],
		normal: integer|integer[3],
		dark: integer|integer[3]): EasyFTLogger

or

addColor(name:string, 
		normal: integer|integer[3]): EasyFTLogger

The normal argument is not optional, but light and dark can be either null or undefined if this colors are not needed.

normal, light and dark can be either an index in the 256-color palette, or an array with the red, green and blue values between 0 and 255.

This method will add every colors for the text (without prefix and also with the c: prefix) abd the colors for the background (with the bg: prefix).

If addColor is called on EasyFTLogger, every logger will be able to use the new color.

EasyFTLogger also provides a static and instance printColors(bg: boolean = false): EasyFTLogger method. If bg is true, the colors are printed in the background.

Converters

If nothing was found in the special characters and in the styles, EasyFTLogger will search for a converter.

A converter is an EasyFTLogger.Converter object with three parmaters:

• name: string
• regExp: RegExp: used to identify the code as convertable. It is recommended to begin with ^ and to end with $ to match the whole code because it avoids collisions between converters.
• convert: Function(result[, ...groups]): string: converts the code. The arguments are all resulting data of the execution of the regular expression.

EasyFTLogger provides a static and instance addConverter method:

addConverter(	name:string, 
				regExp: RegExp,
				convert: Function): EasyFTLogger

Calling the addConverter method on the EasyFTLogger class adds the converter to all existing and future EasyFTLogger object.

Converters: Default Converters

Parsing

An EasyFTLogger object parses the given string to find the %{<code>} statements. <code> cannot contain the } character. <code> can be either a special character, a style or a special type retrieved from a converter. The parsing will search in order:

• Special characters in the specials attribute
• Styles in the styles attribute
• Special types recognized by one of the converter

To preformat a message, use the preformat(message[, ...args]) method with the parameters used by the console log methods. It replaces all the EasyFTLogger statements as explained above. An EasyFTLogger statement which is not recognized is replaced with an empty string. This method returns an object with the following properties:

• message: string: the formated message. Every EasyFTLogger statements where properly replaced and the other javascript statements (like %s or %O)`are remaining.
• arguments: Array: the list of data that relace the js statements such like %s or %O. No EasyFTLogger statement will be replaced in the arguments.
• messageAndArguments: Array: the message is at the first index, and the arguments are at the next indices. This can be used with console.log.apply(console, result.messageAndArguments);

The $preformat(arguments) method can be called with all arguments of preformat(message[, ...args]). It returns the same.

Orphan Logger

Adding a color or a converter directly to the EasyFTLogger class also adds it to the existing instances. To prevent this behavior for a logger, it is possoble to create an orphan logger with the EasyFTLogger.orphanLogger static method.

Syntax Summary