README
@kwaeri-node-kit-console
The @kwaeri/console component for the @kwaeri/node-kit application platform
TOC
The Implementation
@kwaeri/console provides a system to easily style text that is to be sent to the JavaScript console.
The @kwaeri/console component offers an eloquent API featuring methods for setting background color, foreground color, and text effects. Additional methods offer a means to buffer portions of text, to manipulate the styles of each portion, and to dump the result as a collective whole.
Getting Started
The following sections cover how to get started with @kwaeri/console. For a more formal experience, browse the online documentation.
Installation
Start off by installing the module in your project:
npm install @kwaeri/console
Usage
To leverage the console module, you'll first need to include it:
// INCLUDES
import { Console } from '@kwaeri/console';
Follow up by creating an instance of the Console object:
// DEFINES
let output = new Console( { color: false, background: false, decor: [] } );
Now you're ready to start formatting text.
Color
To set the color of any subsequently buffered text, use the color method:
output.color( 'blue' );
The following colors are available to choose from:
- black
- red
- green
- yellow
- blue
- magenta
- cyan
- white
- gray
Background
To set the background color of any subsequently buffered text, use the background method:
output.background( 'black' );
The following background colors are available to choose from:
- black
- red
- green
- yellow
- blue
- magenta
- cyan
- white
Decor
To apply a variety of text decorations to any subsequently buffered text, use the decor method:
output.decor( ['bright'] );
The following text decorations are available to choose from:
- bright
- dim
- underline
- blink (Probably isn't going to work for you...)
- reverse
- hidden
Normalize
When you want to reset the state of the styling, use the normalize method:
output.normalize();
This will clear the background and foreground colors, as well as clear and text decorations.
Clear
When you want to clear any buffered text, use the clear method:
output.clear();
The clear method clears the stack of buffered text.
Buffer
When you want to buffer portions of styled text, use the buffer method:
output.buffer( 'This is some sample text' );
Each call to buffer adds a layer to the stack.
Dump
When you want to combine the portions of text which have been buffered, use the dump method:
console.log( output.dump() );
Each layer of the stack is joined to form a string. Once the stack has been dumped, it has also been cleared, so you are left with a fresh slate.
Keep in mind, however, that the styling does not normalize from a call to dump().
Putting it Together
Here's an example where we put it all together to create a colorful message for the console:
// INCLUDES
import { Console } from '@kwaeri/console';
// DEFINES
let output = new Console( { color: false, background: false, decor: [] } );
// Here we create an error message for a module that takes command line arguments:
let errorMessage = output.color( 'red' ).decor( ['bright'] ).buffer( '[ERROR]' )
.normalize().buffer( ': Invalid Command. \'' + quest + '\' is not a valid command. See ' )
.color( 'blue' ).decor( ['bright'] ).buffer( '--help ' )
.normalize().buffer( 'for a list of commands you can execute.' )
.dump();
console.log( errorMessage );
// The output object is normalized if you couldn't tell, so we have a fresh slate
// to continue with...
How to Contribute Code
Our Open Source projects are always open to contribution. If you'd like to cocntribute, all we ask is that you follow the guidelines for contributions, which can be found at the Massively Modified Wiki
There you'll find topics such as the guidelines for contributions; step-by-step walk-throughs for getting set up, Coding Standards, CSS Naming Conventions, and more.
Other Ways to Contribute
There are other ways to contribute to the project other than with code. Consider testing the software, or in case you've found an Bug - please report it. You can also support the project monetarly through donations via PayPal.
Regardless of how you'd like to contribute, you can also find in-depth information for how to do so at the Massively Modified Wiki
Bug Reports
To submit bug reports, request enhancements, and/or new features - please make use of the issues system baked-in to our source control project space at Gitlab
You may optionally start an issue, track, and manage it via email by sending an email to our project's support desk.
For more in-depth documentation on the process of submitting bug reports, please visit the Massively Modified Wiki on Bug Reports
Vulnerability Reports
Our Vulnerability Reporting process is very similar to Gitlab's. In fact, you could say its a fork.
To submit vulnerability reports, please email our Security Group. We will try to acknowledge receipt of said vulnerability by the next business day, and to also provide regular updates about our progress. If you are curious about the status of your report feel free to email us again. If you wish to encrypt your disclosure email, like with gitlab - please email us to ask for our GPG Key.
Please refrain from requesting compensation for reporting vulnerabilities. We will publicly acknowledge your responsible disclosure, if you request us to do so. We will also try to make the confidential issue public after the vulnerability is announced.
You are not allowed, and will not be able, to search for vulnerabilities on Gitlab.com. As our software is open source, you may download a copy of the source and test against that.
Confidential Issues
When a vulnerability is discovered, we create a [confidential issue] to track it internally. Security patches will be pushed to private branches and eventually merged into a security branch. Security issues that are not vulnerabilites can be seen on our public issue tracker.
For more in-depth information regarding vulnerability reports, confidentiality, and our practices; Please visit the Massively Modified Wiki on Vulnerability
Donations
If you cannot contribute time or energy to neither the code base, documentation, nor community support; please consider making a monetary contribution which is extremely useful for maintaining the Massively Modified network and all the goodies offered free to the public.
