@dogmalang/fs.async

API for interacting with the file system, asynchronously.

Developed in Dogma, compiled to JavaScript.

Engineered in Valencia, Spain, EU by DogmaLang.

Use

////////////////
// JavaScript //
////////////////
const fs = require("@dogmalang/fs.async");

#########
# Dogma #
#########
use "@dogmalang/fs.async" as fs

Entry

For getting an existent file/dir, use:

////////////////
// JavaScript //
////////////////
fs.entry(...path) : Entry

#########
# Dogma #
#########
fn fs.entry(...path) : Entry

fs.exists()

For checking if an entry exists:

////////////////
// JavaScript //
////////////////
async fs.exists(...path) : bool

#########
# Dogma #
#########
async fn fs.exists(...path) : bool

Example:

await(fs.exists("my.txt"))
await(fs.exists("mydir"))

fs.mv() or fs.move()

For moving an entry from a location to another:

////////////////
// JavaScript //
////////////////
async fs.mv(src:string, dst:string)
async fs.mv(src:string, dst:string, {overwrite:bool})

#########
# Dogma #
#########
async proc fs.mv(src:text, dst:text)
async proc fs.mv(src:text, dst:text, opts:{overwrite?:bool})

• src, the source path.
• dst, the destination path.
• overwrite, overwrite if destination existing? Default: true.

Example:

await(fs.mv("one.txt", "two.txt"))

Files

For getting a file object:

////////////////
// JavaScript //
////////////////
fs.file(...path) : File

#########
# Dogma #
#########
fn fs.file(...path) : File

If the file doesn't exist, no error raised.

Example:

f = fs.file("mydir", "myfile")

File.exists() or fs.isFile()

Check whether the file exists:

////////////////
// JavaScript //
////////////////
async exists() : boolean
async fs.isFile(...path) : boolean

#########
# Dogma #
#########
async fn File.exists() : bool
async fn fs.isFile(...path) : bool

Example:

await(fs.file("myfile.txt").exists())
await(fs.isFile("myfile.txt"))

File.rm(), File.remove() and fs.rm()

Remove the file:

////////////////
// JavaScript //
////////////////
async rm()
async fs.rm(...path)

#########
# Dogma #
#########
async proc File.rm()
async proc fs.rm(...path)

If the file doesn't exist, no error raised.

Example:

await(fs.file("myfile.txt").rm())
await(fs.rm("myfile.txt"))

File.len() or File.size()

Return the size in bytes:

////////////////
// JavaScript //
////////////////
async size() : number

#########
# Dogma #
#########
async fn File.size() : num

Example:

await(fs.file("myfile.txt").size())

File.ensure()

Create the file if this doesn't exist:

////////////////
// JavaScript //
////////////////
async ensure()

#########
# Dogma #
#########
async proc File.ensure()

If the file exists, this is not modified.

Example:

await(fs.file("my.txt").ensure())

File.json()

If the file contains a JSON data, it is returned:

////////////////
// JavaScript //
////////////////
async json() : any

#########
# Dogma #
#########
async fn File.json() : any

Example:

obj = await(fs.file("my.json").json())

File.read() or File.c()

Read its content:

////////////////
// JavaScript //
////////////////
async read() : any
async read(encoding:string) : any
async read({encoding}) : any

#########
# Dogma #
#########
async fn File.read() : any
async fn File.read(encoding:text) : any
async fn File.read(opts:{encoding:text}) : any

• encoding: utf-8, utf8...

Example:

txt = await(fs.file("my.txt").read())

File.write()

Write its content:

////////////////
// JavaScript //
////////////////
async write(content)
async write(content, encoding:string)
async write(content, {encoding:string})

#########
# Dogma #
#########
async proc File.write(content)
async proc File.write(content, encoding:text)
async proc File.write(content, opts:{encoding:text})

Example:

await(fs.file("my.txt").write("this is the content"))

File.add() or File.append()

Append content at the end of the file:

////////////////
// JavaScript //
////////////////
async append(c)
async append(c, encoding:string)
async append(c, {encoding:string})

#########
# Dogma #
#########
async proc File.append(c)
async proc File.append(c, encoding:text)
async proc File.append(c, opts:{encoding:text})

Example:

await(fs.file("my.txt").append("end!"))

File.moveTo(), File.mvTo(), fs.move() or fs.mv()

Move the file to a new location:

////////////////
// JavaScript //
////////////////
async moveTo(...path)
async fs.move(from:string, to:string)
async fs.move(from:string, to:string, {overwrite:boolean})

#########
# Dogma #
#########
async proc moveTo(...path)
async proc fs.move(from:text, to:text)
async proc fs.move(from:text, to:text, {overwrite:bool})

Example:

await(fs.file("a.txt").moveTo("b.txt"))
await(fs.mv("a.txt", "b.txt"))

Directories

For getting a directory object:

////////////////
// JavaScript //
////////////////
fs.dir(...path) : Dir

#########
# Dogma #
#########
fn fs.dir(...path) : Dir

If the directory doesn't exist, no error raised.

Example:

f = fs.dir("my", "dir")

Dir.exists() or fs.isDir()

Check whether the directory exists:

////////////////
// JavaScript //
////////////////
async exists() : boolean
async fs.isDir(...path) : boolean

#########
# Dogma #
#########
async fn Dir.exists() : bool
async fn fs.isDir(...path) : bool

Example:

await(fs.dir("my", "dir").exists())
await(fs.isDir("my", "dir"))

Dir.ensure()

Create the directory if this doesn't exist:

////////////////
// JavaScript //
////////////////
async ensure()

#########
# Dogma #
#########
async proc Dir.ensure()

If the directory exists, this is not modified.

Example:

await(fs.dir("mydir").ensure())

Dir.rm(), Dir.remove() and fs.rm()

Remove the directory:

////////////////
// JavaScript //
////////////////
async rm()
async fs.rm(...path)

#########
# Dogma #
#########
async proc Dir.rm()
async proc fs.rm(...path)

If the directory doesn't exist, no error raised.

Example:

await(fs.dir("my", "dir").rm())
await(fs.rm("my", "dir"))

Dir.read()

Return the entries:

////////////////
// JavaScript //
////////////////
async read() : Entry[]
async read({name:string}) : Entry[]

#########
# Dogma #
#########
async fn Dir.read() : list
async fn Dir.read(opts:{name:text}) : list

• name. When full, the entry name contains the full name.

Example:

entries = await(fs.dir("mydir").read())

Dir.file()

Similar to fs.file(dir.path, "file"):

////////////////
// JavaScript //
////////////////
file(...subpath) : File

#########
# Dogma #
#########
fn Dir.file(...subpath) : File

Example:

file = fs.dir("mydir").file("child")

Dir.dir()

Similar to fs.dir(dir.path, "dir"):

////////////////
// JavaScript //
////////////////
dir(...subpath) : Dir

#########
# Dogma #
#########
fn Dir.dir(...subpath) : Dir

Example:

dir = fs.dir("mydir").dir("child")