Skip to content

Commit

Permalink
Refactor docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Kikobeats
Kikobeats committed Sep 15, 2017
1 parent 44041fc commit a6b6ec8
Show file tree
Hide file tree
Showing 2 changed files with 96 additions and 122 deletions.
212 changes: 96 additions & 116 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
[![NPM Status](http://img.shields.io/npm/dm/acho.svg?style=flat-square)](https://www.npmjs.org/package/acho)
[![Donate](https://img.shields.io/badge/donate-paypal-blue.svg?style=flat-square)](https://paypal.me/kikobeats)

> Simple & hackable log system for NodeJS.
> The Hackable Log
# Why

Expand All @@ -29,55 +29,22 @@
npm install acho
```

If you want to use it in the browser (powered by [Browserify](http://browserify.org/)):

```bash
bower install acho --save
```

and later add it to your HTML:

```html
<script src="bower_components/acho/dist/acho.js"></script>
```

## Usage

### First steps

Acho exports itself according to UMD best practices, which means that no matter where you are using the library, you get a version tailored for your environment.

If you're using a module loader (or Node), simple require the library as you would any other module.

If you're using a browser, the library falls back to attaching itself to window as the global `Acho`.

#### CommonJS
The first thing you need to do is create a new log instance:

```js
var Acho = require('acho');
var acho = Acho();
const log = acho()
```

#### Global/Browser
Then you can print one of the defaults logging levels:

```js
var acho = Acho();
```

#### AMD

I don't personally use AMD, so I can't conjure an example, but it should work fine as well.

It's time to use it!

<p align="center">
<br>
<img src="docs/images/00.png" alt="acho">
<br>
</p>

```js
acho.info('hello world');
const log = acho()
const types = Object.keys(log.types)
types.forEach(type => {
log[type]('hello world')
})
```

All public methods are chainable:
Expand All @@ -94,45 +61,7 @@ acho
.error('something bad happens');
```

Maybe you don't want to output the message, but store it for later use:

<p align="center">
<br>
<img src="docs/images/02.png" alt="acho">
<br>
</p>

```js
acho.push('success', 'good job', 'well done', 'great!');
console.log(acho.messages.success);
```

If you want to print previously stored messages, just call the method `print`:

<p align="center">
<br>
<img src="docs/images/03.png" alt="acho">
<br>
</p>

```js
acho.print()
```

You might be thinking: Can I combine both, to store and both print a message? Absolutely!

<p align="center">
<br>
<img src="docs/images/04.png" alt="acho">
<br>
</p>

```js
acho.add('info', 'this message is printed and stored');
console.log(acho.messages.info)
```

### Defining the level
### Logging level

Establishing the loglevel is a good way to filter out undesired information from output. The available levels by default are:

Expand All @@ -150,52 +79,65 @@ Additionally exists two special levels:
The default log level is `all`. You can define it in the constructor:

```js
var acho = Acho({level: 'debug'})
const log = acho({level: 'debug'})
```

or at runtime:

```js
acho.level = 'debug';
log.level = 'debug';
```

See more at [examples/levels](https://github.com/achohq/acho/blob/master/examples/levels.js).

### Customization
### Customize logging levels

You can completely customize the library to your requirements: changes colors, add more types, sort the priorities... the internal structure of the object is public and you can edit it dynamically. **You have the power**.
### skin-cli
### skin-syslog

By default the messages structure is brief: Just the message type followed by the message itself.
### Internal Store

But you can easily modify the output. For example, let's add a timestamp to each message:
Sometimes, when you are interacting with a logger you need to store the logs to be used later instead of print all of them.

We define `.push` as accumulator for store the log internally:

<p align="center">
<br>
<img src="docs/images/05.png" alt="acho">
<img src="docs/images/02.png" alt="acho">
<br>
</p>

```js
var acho = Acho({
color: true,
level: 'debug',
acho.push('success', 'good job', 'well done', 'great!');
console.log(acho.messages.success);
```

// Customize how to print the 'type' of each message
outputType: function(type) {
return '[' + type + '] » ';
},
If you want to print previously stored messages, just call the method `print`:

// Customize how to print the message.
// Add things before and/or after.
outputMessage: function(message) {
return Date() + ' :: ' + message;
}
});
<p align="center">
<br>
<img src="docs/images/03.png" alt="acho">
<br>
</p>

acho.info('I am hungry');
```js
acho.print()
```

If you need customize more the output you can setup `.print` `.generateMessage` (see below) that are a more low level methods for generate and print the output message.
or you can retrieve the logs programatically from the internal storage at `acho.messages`

The method `.add` combine `.push` and `.print` actions in one: It store the message internally but also print the log.

<p align="center">
<br>
<img src="docs/images/04.png" alt="acho">
<br>
</p>

```js
acho.add('info', 'this message is printed and stored');
console.log(acho.messages.info)
```

## Formatters

Expand Down Expand Up @@ -243,43 +185,79 @@ acho.info('formatting with object interpolation %J', {

See more at [examples/formatter](https://github.com/achohq/acho/blob/master/examples/formatter.js).

## API
### Customization

You can completely customize the library to your requirements: changes colors, add more types, sort the priorities... the internal structure of the object is public and you can edit it dynamically. **You have the power**.

By default the messages structure is brief: Just the message type followed by the message itself.

But you can easily modify the output. For example, let's add a timestamp to each message:

### Acho({Object} [options])
<p align="center">
<br>
<img src="docs/images/05.png" alt="acho">
<br>
</p>

Create a logger. Available options:
```js
var acho = Acho({
color: true,
level: 'debug',

<img src="docs/images/07.png" align="right">
// Customize how to print the 'type' of each message
outputType: function(type) {
return '[' + type + '] » ';
},

// Customize how to print the message.
// Add things before and/or after.
outputMessage: function(message) {
return Date() + ' :: ' + message;
}
});

acho.info('I am hungry');
```

If you need customize more the output you can setup `.print` `.generateMessage` (see below) that are a more low level methods for generate and print the output message.

## API

### Acho([options])

It creates a logger instance. Available options:

##### **{String}** keyword

![](docs/images/07.png)

Default: `loglevel`

Instead of print the type log level, print the keyword. By default this behavior is not activated.

You can pass the special keyword `symbol` to show an unicode icon. This is special behavior for CLI programs.

<img src="docs/images/08.png" align="right">

##### **{String}** align

![](docs/images/08.png)

Default: `' '`

It adds an alignment separator between the type of the message and the message.

You can provide your own separator or disable it providing a `false`.

<img src="docs/images/06.png" align="right">

##### **{Boolean}** diff

![](docs/images/06.png)

Default: `false`

Prints timestamp between log from the same level. Specially useful to debug timmings.
Prints timestamp between log from the same level. Specially useful to debug timings.

##### **{Boolean}** color

Default: `false`.
Default: `true`.

Enable or disable colorized output.

Expand All @@ -289,11 +267,13 @@ Default: `false`.

Enable or disable print log level in upper case.

##### **{Number}** timestamp
##### **{Boolean|Number}** timestamp

Default: `false`.

Default: `0`.
Prints a numeric counter timestamp associated with each log line.

Prints a counter timestamp associated with each log line. Useful for debug log traces.
The value provided is the minimum quantity of time in milliseconds to consider print a different counter.

##### **{Number}** offset

Expand Down
6 changes: 0 additions & 6 deletions component.json
View file

This file was deleted.

0 comments on commit a6b6ec8

Please sign in to comment.