atma-io

File / Directory Classes

npm install atma-io
113 downloads in the last week
216 downloads in the last month

Atma Node.js IO Module

Build Status

Features:

  • File Class
  • Directory Class
  • File read/write Middleware
  • Sync

Mostly all operations are synchronous, and this is really useful in case of script applications or desktop applications, where the synchronous performance is not critical.

This library is included into Atma.Toolkit, so creating custom scripts, you can use this API.

File

File methods

File constructor
var file = new io.File('test.txt');

Path is always relative to the cwd (except windows os, when drive letter is used). To specify system absolute path, use file:// protocol.

read
var content = file.read( <?Object> {
    encoding: String | null, //> 'utf8'
    skipHooks: Boolean //> false
});

Read file's content. If encoding is set to null raw Buffer is returned. For each read middleware pipeline is used, to skip it, set skipHooks to true.

write
file.write(String | Buffer, <?Object>{
    skipHooks: Boolean
});
exists
file.exists() //> Boolean;
copyTo
file.copyTo(<String> location) //> Boolean;
rename
file.rename(<String> filename)
remove
file.remove()
watch
file.watch(callback)

Watch file for changes

unwatch
file.unwatch(callback) //> Boolean;

Cache

Each read will be cached. To control cache behaviour use next methods:

clearCache
io.File.clearCache(<?String> path);

When path is null, then all cache is dropped.

disableCache
io.File.disableCache();
enableCache
io.File.disableCache();

short forms

There are some static methods, so that there is no need to initialize the File instance.

io.File[method] //> Function(filepath, [..args])
// methods:
        'exists'
        'read'
        'write'
        'remove'
        'copyTo'

File Middleware

Middleware pattern is used for all reads and writes. It can be used, for example, to compile coffee script to javascript on the fly. Or when reading *.yml file, the resulted content is not a YAML string, but already parsed object.

Extensions

To get the idea, look at the hook definition sample:

io.File.registerExtensions({
    'coffee':[
        'conditions:read',
        'coffee-compiler:read',
        'uglify:write'
    ]
});

Each middleware has unique name and is registerd in this way:

io.File.middleware['coffee'] = {
    read: function(<io.File> file, <Object> config){
        var coffee = require('coffee-script');
        file.content = coffee.compile(file.content);
    },
    write: function(<io.File> file, <Object> config){
        // ... do smth with `content` before disk write
    }
};

Advanced middleware

io
    .File
    .getHookHandler()
    .register({
        regexp: <RegExp>,
        method: <'read'|'write'>,
        handler: <Function | Object> handler,
        zIndex: <?Number> // default: 0
    });

Path is matched by the regexp. The greater zIndex ist the later it is called in a pipeline, otherwise the handlers are called in the order they were registerd.

Embedded middlewares

  • read

    • less ( -> css)
    • coffee ( -> javascript )
    • markdown ( -> html )
    • jshint ( -> run jshint )
    • json ( -> JSON.parse is used )
    • yml ( -> YAML parser is used )
  • write

    • uglify ( -> Minify source before flushing )
    • yml ( -> Stringify object to yml string )
    • json ( -> Stringify object to json )

Virtual Files

Define with RegExp a File Handler to completely override the read/write/exists/remove behaviour.

io
    .File
    .getFactory()
    .registerHandler(/defaults\.json$/i, Class({
        exists: function(){
            return true;
        },
        read: function(){
            return { foo: 'bar' };
        }
    }));

Directory

Directory methods

Constructor
var dir = new io.Directory('src/');

Path is always relative to the cwd (except windows os, when drive letter is used). To specify system absolute path, use file:// protocol.

exists
dir.exists()//> Boolean
readFiles
dir.readFiles(<?String> pattern).files // Array<io.Files>

Get list of all files in the directory. pattern is a glob pattern.

// all javascript files, also from sub-directories
pattern = '*.js';
// only from base directory
pattern = '/*.js'
// only from sub-directories
pattern = '**/*.js'

dir.readFiles(pattern).files
copyTo
dir.copyTo(<String> destination);
rename
dir.rename(<String> folderName);
remove
dir.remove()

Removes all sub directories and all files.

ensure
dir.ensure()

Creates directory structure, if not already exists.

watch
dir.watch(callback)

Watch directory for changes

unwatch
dir.unwatch(callback)
short forms

There are some static methods, so that there is no need to initialize the Directory instance.

io.Directory[method] //> Function(dirpath, [..args])
// methods:
    'exists',
    'readFiles',
    'ensure',
    'remove',
    'copyTo'

(c) MIT - Atma.js Project

npm loves you