1 | # Tail
|
2 |
|
3 | The **zero** dependency Node.js module for tailing a file
|
4 |
|
5 | [![NPM](https://nodei.co/npm/tail.png?downloads=true&downloadRank=true)](https://nodei.co/npm/tail.png?downloads=true&downloadRank=true)
|
6 |
|
7 | [![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/lucagrulla/node-tail/blob/master/LICENSE)
|
8 | [![npm](https://img.shields.io/npm/v/tail.svg?style=plastic)](https://www.npmjs.com/package/tail)
|
9 |
|
10 | Author: [Luca Grulla](https://www.lucagrulla.com) - [www.lucagrulla.com](https://www.lucagrulla.com)
|
11 |
|
12 | ## Installation
|
13 |
|
14 | ```bash
|
15 | npm install tail
|
16 | ```
|
17 |
|
18 | ## Use:
|
19 |
|
20 | ```javascript
|
21 | Tail = require('tail').Tail;
|
22 |
|
23 | tail = new Tail("fileToTail");
|
24 |
|
25 | tail.on("line", function(data) {
|
26 | console.log(data);
|
27 | });
|
28 |
|
29 | tail.on("error", function(error) {
|
30 | console.log('ERROR: ', error);
|
31 | });
|
32 | ```
|
33 |
|
34 | If you want to stop tail:
|
35 |
|
36 | ```javascript
|
37 | tail.unwatch()
|
38 | ```
|
39 |
|
40 | To start watching again:
|
41 |
|
42 | ```javascript
|
43 | tail.watch()
|
44 | ```
|
45 |
|
46 | ## Configuration
|
47 | The only mandatory parameter is the path to the file to tail.
|
48 |
|
49 | ```javascript
|
50 | var fileToTail = "/path/to/fileToTail.txt";
|
51 | new Tail(fileToTail)
|
52 | ```
|
53 |
|
54 | Optional parameters can be passed via a hash:
|
55 |
|
56 | ```javascript
|
57 | var options= {separator: /[\r]{0,1}\n/, fromBeginning: false, fsWatchOptions: {}, follow: true, logger: console}
|
58 | new Tail(fileToTail, options)
|
59 | ```
|
60 |
|
61 | ## Available parameters
|
62 |
|
63 | * `separator`: the line separator token (default: `/[\r]{0,1}\n/` to handle linux/mac (9+)/windows). Pass null if your file is binary there's no line separator.
|
64 | * `fsWatchOptions`: the full set of options that can be passed to `fs.watch` as per node documentation (default: {}).
|
65 | * `fromBeginning`: forces the tail of the file from the very beginning of it instead of from the first new line that will be appended (default: `false`).
|
66 | * `follow`: simulate `tail -F` option. In the case the file is moved/renamed (or logrotated), if set to `true` `tail` will try to start tailing again after a 1 second delay, if set to `false` it will just emit an error event (default: `true`).
|
67 | * `logger`: a logger object(default: no logger). The passed logger has to respond to two methods:
|
68 | * `info([data][, ...])`
|
69 | * `error([data][, ...])`
|
70 | * `useWatchFile`: if set to `true` will force the use of `fs.watchFile` rather than delegating to the library the choice between `fs.watch` and `fs.watchFile` (default: `false`).
|
71 | * `encoding`: the encoding of the file to tail (default:`utf-8`).
|
72 | * `flushAtEOF`: set to `true` if you want to force flush of content when end of file is reached. Particularly useful when there's no separator character at the end of the file (default: `false`).
|
73 |
|
74 | ## Emitted events
|
75 |
|
76 | `Tail` emits two events:
|
77 |
|
78 | * line
|
79 |
|
80 | ```javascript
|
81 | function(data){
|
82 | console.log(data)
|
83 | }
|
84 | ```
|
85 |
|
86 | * error
|
87 |
|
88 | ```javascript
|
89 | function(exception){}
|
90 | ```
|
91 |
|
92 | ## How to contribute
|
93 |
|
94 | Tail is written in [CoffeeScript](http://jashkenas.github.com/coffee-script/).
|
95 |
|
96 | The Cakefile generates the javascript that is then published to npm.
|
97 |
|
98 | ## History
|
99 |
|
100 | Tail was born as part of a data firehose. Read about it [here](https://www.lucagrulla.com/posts/building-a-firehose-with-nodejs/).
|
101 |
|
102 | ## License
|
103 |
|
104 | MIT. Please see License file for more details.
|