atma-io
File / Directory Classes
Last updated 4 months ago by tenbits .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install atma-io 
SYNC missed versions from official npm registry.

Atma Node.js FileSystem Module

Build Status NPM version

Features:

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

In comparison to NodeJS sync-async contract: all functions with generic name are synchronous, and the **Async are asynchronous with the same interface and return deferred object. Sync versions never throw exceptions and are designed to be used in not performance critical applications, like bash scripts, etc.

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

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.

var content = file.read( <?Object> {
    encoding: String | null, //> 'utf8'
    skipHooks: Boolean //> false
});
readAsync
file
	.readAsync( <?Object> {
		encoding: String | null, //> 'utf8'
		skipHooks: Boolean //> false
	})
	.done(function(content, file))
	.fail(function(error))
write
file.write(String | Buffer, <?Object>{
    skipHooks: Boolean
})
writeAsync
file
	.writeAsync(String | Buffer, <?Object>{
		skipHooks: Boolean
	})
	.done(function())
	.fail(function(error))
exists
file.exists(): boolean
copyTo
interface IFileCopyOpts {
    silent?: boolean
    baseSource?: string 
}
/**
 * @param path: Target file path or directory, when ends with slash
 */
file.copyTo(path: string, opts?: IFileCopyOpts): boolean
copyToAsync
file.copyToAsync(path: string, opts?: IFileCopyOpts): Promise<boolean>
rename
file.rename(filename: string)
renameAsync
file.renameAsync(filename: string): Promise<void>
replace

Reads the content as string, replaces the matches and writes the result. Expected arguments are the same as for JavaScripts String replace. Returns new content.

.replace(string | RegExp, string | Function): string
replaceAsync
.replaceAsync(string | RegExp, string | Function): Promise<string>
remove
file.remove()
removeAsync
file.removeAsync(): Promise<void>
watch
file.watch(cb: (path) => void)

Watch file for changes

unwatch
file.unwatch(cb?: (path) => void): boolean

Cache

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

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

When path is null, then all cache is dropped.

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

short forms

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

File[method] //> Function(filepath, [..args])
// methods:
        'exists'
		'existsAsync'
        'read'
		'readAsync'
        'write'
		'writeAsync'
        'remove'
		'removeAsync',
		'replace',
		'replaceAsync',
		'rename'
		'renameAsync'
        'copyTo'
		'copyToAsync'

// sample
io
	.File
	.readAsync('/baz.txt')
	.done(function(content){
		console.log(content);
	})
	.fail(function(error){
		console.error(error);
	})
	;

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

Lately will be converted into plugins, @see Plugins

  • read

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

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

Middleware Plugins

There additional read/write middlewares as atma plugins:

atma plugin install NAME
  • atma-loader-traceur - Traceur
  • atma-loader-less - Less
Combined middlewares

For example, you want to use Traceur middelware and jshint for reading js files: via javascript

io.File.registerExtensions({
	js: ['hint:read', 'atma-loader-traceur:read' /* ... */],
})

via package.json

...
"atma": {
	"settings" : {
		"io": {
			"extensions": {
				"js": [ "hint:read", "atma-loader-traceur:read" ]
			}
		}
	}
}

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
existsAsync
dir.existsAsync()//> Deferred
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
readFilesAsync
dir
	.readFilesAsync(<?String> pattern)
	.done(function(files))
	.fail(function(error))
copyTo

Copy files to destination directory. Before copying dir.readFiles can be called to copy only specific files.

dir.copyTo(destination: string)
copyToAsync
dir.copyToAsync(destination: string) //> Deferred
rename
dir.rename(<String> folderName);
renameAsync
dir.renameAsync(<String> folderName) //> Deferred
remove

Removes all content recursively and the folder itself

dir.remove() //> Boolean
removeAsync
dir.removeAsync()
ensure
dir.ensure()

Creates directory structure, if not already exists.

ensureAsync
dir.ensureAsync()
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'
	'existsAsync'
    'readFiles'
	'readFilesAsync'
    'ensure'
	'ensureAsync'
    'remove'
	'removeAsync'
    'copyTo'
	'copyToAsync'
	
// sample
io
	.Directory
	.readFilesAsync('sub/', '**.js')
	.done(function(files))
	.fail(function(error))

(c) MIT - Atma.js Project

Current Tags

  • 1.2.29                                ...           latest (4 months ago)

129 Versions

  • 1.2.29                                ...           4 months ago
  • 1.2.28                                ...           4 months ago
  • 1.2.27                                ...           5 months ago
  • 1.2.26                                ...           a year ago
  • 1.2.25                                ...           a year ago
  • 1.2.24                                ...           a year ago
  • 1.2.22                                ...           a year ago
  • 1.2.21                                ...           a year ago
  • 1.2.20                                ...           a year ago
  • 1.2.19                                ...           a year ago
  • 1.2.17                                ...           a year ago
  • 1.2.16                                ...           a year ago
  • 1.2.15                                ...           a year ago
  • 1.2.14                                ...           a year ago
  • 1.2.13                                ...           a year ago
  • 1.2.12                                ...           a year ago
  • 1.2.11                                ...           a year ago
  • 1.2.10                                ...           a year ago
  • 1.2.9                                ...           a year ago
  • 1.2.8                                ...           a year ago
  • 1.2.6                                ...           a year ago
  • 1.2.5                                ...           a year ago
  • 1.2.4                                ...           a year ago
  • 1.2.3                                ...           a year ago
  • 1.2.2                                ...           a year ago
  • 1.2.1                                ...           a year ago
  • 1.1.7                                ...           2 years ago
  • 1.1.6                                ...           2 years ago
  • 1.1.5                                ...           2 years ago
  • 1.1.4                                ...           2 years ago
  • 1.1.3                                ...           2 years ago
  • 1.1.2                                ...           2 years ago
  • 1.1.1                                ...           2 years ago
  • 1.1.0                                ...           2 years ago
  • 1.0.7                                ...           2 years ago
  • 1.0.6                                ...           2 years ago
  • 1.0.4                                ...           2 years ago
  • 1.0.3                                ...           2 years ago
  • 1.0.2                                ...           2 years ago
  • 1.0.1                                ...           2 years ago
  • 0.2.40                                ...           3 years ago
  • 0.2.39                                ...           3 years ago
  • 0.2.38                                ...           3 years ago
  • 0.2.37                                ...           3 years ago
  • 0.2.36                                ...           3 years ago
  • 0.2.35                                ...           3 years ago
  • 0.2.34                                ...           3 years ago
  • 0.2.33                                ...           3 years ago
  • 0.2.32                                ...           3 years ago
  • 0.2.31                                ...           3 years ago
  • 0.2.30                                ...           3 years ago
  • 0.2.29                                ...           3 years ago
  • 0.2.28                                ...           3 years ago
  • 0.2.27                                ...           3 years ago
  • 0.2.26                                ...           3 years ago
  • 0.2.25                                ...           3 years ago
  • 0.2.24                                ...           3 years ago
  • 0.2.23                                ...           3 years ago
  • 0.2.22                                ...           3 years ago
  • 0.2.21                                ...           3 years ago
  • 0.2.19                                ...           3 years ago
  • 0.2.18                                ...           4 years ago
  • 0.2.17                                ...           4 years ago
  • 0.2.16                                ...           4 years ago
  • 0.2.15                                ...           4 years ago
  • 0.2.14                                ...           4 years ago
  • 0.2.13                                ...           4 years ago
  • 0.2.12                                ...           5 years ago
  • 0.2.11                                ...           5 years ago
  • 0.2.10                                ...           5 years ago
  • 0.2.9                                ...           5 years ago
  • 0.2.8                                ...           5 years ago
  • 0.2.7                                ...           5 years ago
  • 0.2.6                                ...           5 years ago
  • 0.2.5                                ...           5 years ago
  • 0.2.4                                ...           5 years ago
  • 0.2.3                                ...           5 years ago
  • 0.2.2                                ...           6 years ago
  • 0.2.1                                ...           6 years ago
  • 0.2.0                                ...           6 years ago
  • 0.1.92                                ...           6 years ago
  • 0.1.91                                ...           6 years ago
  • 0.1.90                                ...           6 years ago
  • 0.1.89                                ...           6 years ago
  • 0.1.88                                ...           6 years ago
  • 0.1.87                                ...           6 years ago
  • 0.1.86                                ...           6 years ago
  • 0.1.85                                ...           6 years ago
  • 0.1.83                                ...           6 years ago
  • 0.1.82                                ...           6 years ago
  • 0.1.81                                ...           6 years ago
  • 0.1.80                                ...           6 years ago
  • 0.1.78                                ...           6 years ago
  • 0.1.77                                ...           6 years ago
  • 0.1.76                                ...           6 years ago
  • 0.1.75                                ...           6 years ago
  • 0.1.74                                ...           6 years ago
  • 0.1.73                                ...           6 years ago
  • 0.1.72                                ...           6 years ago
  • 0.1.71                                ...           6 years ago
  • 0.1.70                                ...           6 years ago
  • 0.1.69                                ...           6 years ago
  • 0.1.68                                ...           6 years ago
  • 0.1.66                                ...           6 years ago
  • 0.1.65                                ...           6 years ago
  • 0.1.64                                ...           6 years ago
  • 0.1.63                                ...           6 years ago
  • 0.1.62                                ...           6 years ago
  • 0.1.60                                ...           6 years ago
  • 0.0.60                                ...           6 years ago
  • 0.0.59                                ...           6 years ago
  • 0.0.58                                ...           6 years ago
  • 0.0.57                                ...           7 years ago
  • 0.0.56                                ...           7 years ago
  • 0.0.55                                ...           7 years ago
  • 0.0.54                                ...           7 years ago
  • 0.0.53                                ...           7 years ago
  • 0.0.52                                ...           7 years ago
  • 0.0.51                                ...           7 years ago
  • 0.0.50                                ...           7 years ago
  • 0.0.49                                ...           7 years ago
  • 0.0.48                                ...           7 years ago
  • 0.0.47                                ...           7 years ago
  • 0.0.46                                ...           7 years ago
  • 0.0.45                                ...           7 years ago
  • 0.0.44                                ...           7 years ago
  • 0.0.42                                ...           7 years ago
  • 0.0.41                                ...           7 years ago
  • 0.0.4                                ...           7 years ago
Maintainers (1)
Downloads
Today 0
This Week 2
This Month 2
Last Day 0
Last Week 0
Last Month 3
Dependencies (2)
Dev Dependencies (7)

Copyright 2014 - 2017 © taobao.org |