A list of examples is provided in [`/examples`](/examples).
# Documentation
ScribeJS is divided is 4 main modules :
- [Console2](#Console2) : an extended console object
- [LogWriter](#LogWriter) : an utility to save logs on disk
- [WebPanel](#WebPanel) : a rich HTML logs explorer
- [ExpressLogger](#ExpressLogger) : an utility to logs all express request
It all starts by adding ScribeJS to your js file :
```javascript
require('scribe')();
var console = process.console;
```
Use this import if you don't need do configure anything. It will attach a new Console2 instance on `process.console` and create [basic loggers](#basic-loggers).
Or :
```javascript
var scribe = require('scribe')();
```
Use this import if you want to configure or custom something.
###scribe(config)
**Params** :
-`config` : *Optional.*
-`rootPath` : logs folder for LogWriter. Default `/logs`
-`createDefaultConsole` : Boolean. If `true` : create a Console2 instance attached to `process.console`. Default `true`. See [Using Scribe through your modules](#using-scribe-through-your-modules)
**Return** : an object with this properties
-`console`
-`webPanel`
-`express`
-`LogWriter`
-`Console2`
###scribe.console(config, logWriter)
Create a new Console2 instance with LogWriter listening. This is the best way to create a console.
-`console` : *Optional.* An instance of Console2 with an `.info()` logger. If no console provided, Scribe will try to use `process.console` if it exists. If not, it will throw an error.
-`validate` : a filter function that receive `req` and `res` as arguments and should return `true` in order to Scribe to log that request.
Save the new file path in history according to date.
###logWriter.getUser()
Util. Return active system user.
###LogWriter.getPath(opt)
Build the path to current logs folder.
Default return `[YYYY]/[MMM]`
###LogWriter.getFile(opt)
Build the filename.
Default `[DD_MM_YY].[loggerName].json`
###LogWriter.path(opt)
Build the full path to file.
Ie. RootPath + getPath() + getFile()
###LogWriter.save(log, opt)
Save a log on disk
###LogWriter.saveOpt(logger)
Save logger opt in root folder
###LogWriter.addLogger(logger)
Call saveOpt().
###*How logs are saved ?*
LogWriter create an `history.json` file in root folder where it keeps tracks of all logs files created by date.
It also create `[logger name].json` in root folder for each logger where it saves the logger config.
Then, for each day, LogWriter will save logs in a new directory.
### Example
See [`/examples/logWriter_config.js`](/examples/logWriter_config.js) to see how to build your custom log path and pass it to `scribe.console()` function.
## WebPanel
An express router that served and HTML logs explorer.
An utility to log each request made to an express server.
See [`scribe.express.logger()`](#scribe.express.logger(console,-validate))
#Using Scribe through your modules
When running `require('scribe')()` or `require('scribe')({createDefaultConsole : true})` you ask Scribe to attach a fresh console on the NodeJS `process` variable.
As `process` is shared accross all modules you required (the whole process), you can use the Console2 instance in sub-modules.
**Example** :
```javascript
//main.js
require('scribe')();
var sub = require('./sub.js'); //a sub-module
var console = process.console;
console.tag('Hello world').log("We're in the main file")
sub.something();
```
```javascript
//sub.js
//don't require scribe, simply link `process.console`
var console = process.console;
module.exports = {
something : function () {
console.tag("Hello World", "Sub").log("We're in a submodule");
}
};
```
Tip : even if you don't tell scribe to create a default console, you can manually attach a Console2 instance on `process`.
```javascript
//main.js
var scribe = require('scribe')({
createDefaultConsole : false
});
var sub = require('./sub.js'); //a sub-module
var customConsole = scribe.console({ //a new console
//custom
});
process.customConsole = customConsole; //attach it to process
customConsole('Hello world').log("We're in the main file")
sub.something();
```
```javascript
//sub.js
//don't require scribe
var console = process.customConsole;
module.exports = {
something : function () {
console.tag("Hello World", "Sub").log("We're in a submodule");
}
};
```
See :
- [`/examples/run.js`](/examples/run.js)
- [NodeJS process doc](http://nodejs.org/api/process.html)
#Come back to the old console
Scribe overides nothing and doesn't break logging in dependencies. The old NodeJS console is never too far away.
```javascript
require('scribe')();
var console = process.console;
console.time().log("Logging with Scribe")
global.console.log("Logging the old way")
```
```javascript
//in a dependency
console.log("Something") //the old console
```
See : [NodeJS global doc](http://nodejs.org/api/globals.html)
