Skip to content

Documentation - Version Beta

Welcome to the official API reference of Nacre documentation.

Builtins

Builtins are commands available natively in Nacre. They don't need to be imported and can be used right away.

cat

cat(filepath): string

Returns the content of the file in string format (utf-8).

Example:

> cat('foo.txt')
'this a file\nwith text in it'

cat(filepath): string[]

Returns the content of the file in string format (utf-8) split by line.

Example:

> cat('foo.txt')
['this a file', 'with text in it']

cat.overwrite(filepath, string): string

Overwrites the content of the file. Create the file if it does not exist.

Returns the content of the file (string).


cat.append(filepath, string): string

Append string content to the filepath file. The file is created if it does not exist.

Returns the content of the file.

cd

cd(): string

Alias of cd.home();


cd(path: string): string

The method changes the current working directory of the Node.js process to path or throws an exception if doing so fails (for instance, if the specified directory does not exist).

Returns the new current directory.


cd.home(): string

The method changes the current working directory of the Node.js process to your home directory defined by NodeJS os.homedir().

Returns the new current directory.


cd.previous(): string

The method changes the current working directory of the Node.js process to your previous directory. Similar to cd - in Bash.

Returns the new current directory.

chmod

Not available on Windows.

chmod(itemPath): object

Returns the permissions of the itemPath item.

Example:

> chmod('foo')
{
user: { read: true, write: true, execute: false },
group: { read: true, write: false, execute: false },
others: { read: true, write: false, execute: false }
}

chmod.add(itemPath): object

Adds read, write and execution permissions to user, group and others.

Returns the permissions of the itemPath item.


chmod.add.read(itemPath): object

Adds read permission to user, group and others.

Returns the permissions of the itemPath item.


chmod.add.read.user(itemPath): object

Adds read permission to user.

Returns the permissions of the itemPath item.


chmod.add.read.group(itemPath): object

Adds read permission to group.

Returns the permissions of the itemPath item.


chmod.add.read.others(itemPath): object

Adds read permission to others.

Returns the permissions of the itemPath item.


chmod.add.write(itemPath): object

Adds write permission to user, group and others.

Returns the permissions of the itemPath item.


chmod.add.write.user(itemPath): object

Adds write permission to user.

Returns the permissions of the itemPath item.


chmod.add.write.group(itemPath): object

Adds write permission to group.

Returns the permissions of the itemPath item.


chmod.add.write.others(itemPath): object

Adds write permission to others.

Returns the permissions of the itemPath item.


chmod.add.execute(itemPath): object

Adds execution permission to user, group and others.

Returns the permissions of the itemPath item.


chmod.add.execute.user(itemPath): object

Adds execution permission to user, group and others.

Returns the permissions of the itemPath item.


chmod.add.execute.group(itemPath): object

Adds execution permission to group.

Returns the permissions of the itemPath item.


chmod.add.execute.others(itemPath): object

Adds execution permission to others.

Returns the permissions of the itemPath item.


chmod.remove(itemPath): object

Removes read, write and execution permissions to user, group and others.

Returns the permissions of the itemPath item.


chmod.remove.read(itemPath): object

Removes read permission to user, group and others.

Returns the permissions of the itemPath item.


chmod.remove.read.user(itemPath): object

Removes read permission to user.

Returns the permissions of the itemPath item.


chmod.remove.read.group(itemPath): object

Removes read permission to group.

Returns the permissions of the itemPath item.


chmod.remove.read.others(itemPath): object

Removes read permission to others.

Returns the permissions of the itemPath item.


chmod.remove.write(itemPath): object

Removes write permission to user, group and others.

Returns the permissions of the itemPath item.


chmod.remove.write.user(itemPath): object

Removes write permission to user.

Returns the permissions of the itemPath item.


chmod.remove.write.group(itemPath): object

Removes write permission to group.

Returns the permissions of the itemPath item.


chmod.remove.write.others(itemPath): object

Removes write permission to others.

Returns the permissions of the itemPath item.


chmod.remove.execute(itemPath): object

Removes execution permission to user, group and others.

Returns the permissions of the itemPath item.


chmod.remove.execute.user(itemPath): object

Removes execution permission to user, group and others.

Returns the permissions of the itemPath item.


chmod.remove.execute.group(itemPath): object

Removes execution permission to group.

Returns the permissions of the itemPath item.


chmod.remove.execute.others(itemPath): object

Removes execution permission to others.

Returns the permissions of the itemPath item.


chmod.set(itemPath, perm): object

Sets perm permissions.

Returns the permissions of the itemPath item.


chmod.set.read(itemPath): object

Sets read permission to user, group and others. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.read.user(itemPath): object

Sets read permission to user. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.read.group(itemPath): object

Sets read permission to group. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.read.others(itemPath): object

Sets read permission to others. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.write(itemPath): object

Sets write permission to user, group and others. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.write.user(itemPath): object

Removes write permission to Sets. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.write.group(itemPath): object

Sets write permission to group. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.write.others(itemPath): object

Sets write permission to others. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.execute(itemPath): object

Sets execution permission to user, group and others. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.execute.user(itemPath): object

Sets execution permission to user, group and others. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.execute.group(itemPath): object

Sets execution permission to group. Removes permissions to the rest.

Returns the permissions of the itemPath item.


chmod.set.execute.others(itemPath): object

Sets execution permission to others. Removes permissions to the rest.

Returns the permissions of the itemPath item.

chown

Not available on Windows.

chown(itemPath): object

Returns the owner and group of the itemPath item.

Example:

> chown('foo')
{ owner: 'john', group: 'staff' }

chown.get(itemPath): object

Alias to chown().


chown.set(itemPath, username, groupname): object

Set the owner and group of the itemPath item with username and groupname.

Returns the owner and group of the itemPath item.


chown.set.owner(itemPath, username): object

Set the owner of the itemPath item with username.

Returns the owner and group of the itemPath item.


chown.set.group(itemPath, groupname): object

Set the group of the itemPath item with groupname.

Returns the owner and group of the itemPath item.

grep

grep(regex): function

Shortcut of the RegExp test function allowing the code below:

> ['foo', 'bar', 'noodle'].filter(e => /oo/.test(e))
[ 'foo', 'noodle' ]

to be written this way:

> ['foo', 'bar', 'noodle'].filter(grep(/oo/))
[ 'foo', 'noodle' ]

ls

ls(): string[]

Returns the items of the working directory.


ls(dirpath: string): string[]

Returns the items of the dirpath directory.

Note that unlike traditional ls, it will fail if you give a file path in parameter. This is to distinguish a directory from a file within the directory (ex: foo vs foo/foo).


ls.recursive(dirpath: string): string[]

Returns the items of the dirpath directory and subdirectories.

mkdir

mkdir(dirpath: string): string

Synchronously creates a directory.

Returns the dirpath of the created directory.


mkdir.recursive(dirpath: string): string

Synchronously creates a directory and the intermediate directories if necessary.

Returns the dirpath of the created directory.

mv

mv(itemPath: string, dirPath: string): object

Moves the item from itemPath to the directory dirPath.

Return the old and the new path of the moved item.

pwd

pwd(): string

Returns the current working directory. Alias of NodeJS process.cwd().

$ (execute)

Not available on Windows.

$(command: string): string

Executes the command given in argument and returns its output. Example:

> $('ls -l')
'total 88\n' +
'-rw-r--r-- 1 ninroot staff 87 Mar 24 18:23 README.md\n' +
'-rwxr--r-- 1 ninroot staff 19 Mar 24 21:34 myscript.sh\n' +
'drwxr-xr-x 35 ninroot staff 1120 Mar 25 02:37 node_modules\n' +
'-rw-r--r-- 1 ninroot staff 74 Mar 25 02:37 package.json\n'

stat

stat(itemPath): object

Returns the information of the given item. Example:

> stat('myDir')
{
name: 'myDir',
type: 'directory',
size: 160,
createdAt: 2022-02-10T10:20:52.844Z,
modifiedAt: 2022-02-10T10:20:52.844Z,
owner: 'me',
group: 'staff'
}

touch

touch(itemPath): string

Sets the modification and access times of the item located at itemPath. If the item does not exist, it creates an empty file at the itemPath location.

Returns the location of the item.

Commands

npm

npm.install(npmPackage: string): NpmPackage;

Install a package and any packages that it depends on. Details here.

Example:

> npm.install('chalk')
{
added: 1,
removed: 0,
changed: 0,
name: 'chalk',
version: '5.0.1',
resolved: 'https://registry.npmjs.org/chalk/-/chalk-5.0.1.tgz'
}

Uninstalls a package, completely removing everything npm installed on its behalf. Details here.

npm.uninstall(packageName: string): NpmPackage;

Example:

> npm.uninstall('chalk')
{
name: 'chalk',
version: '5.0.1',
resolved: 'https://registry.npmjs.org/chalk/-/chalk-5.0.1.tgz',
added: 0,
removed: 1,
changed: 0
}

Shortcuts

Nacre uses NodeJS readline, some shortcuts are defined there too.

ShortcutDescription
<ctrl> + CQuit Nacre / Remove the current line
<ctrl> + HDelete previous character
<ctrl> + UDelete from the current cursor to the line start
<ctrl> + KDelete from the current cursor to the line end
<ctrl> + AMove the cursor to the begining of the line
<ctrl> + EMove the cursor to the end of the line
<ctrl> + BMove the cursor back one character
<ctrl> + FMove the cursor forward one character
<ctrl> + LClear the screen of the terminal
<ctrl> + NNext history item
<ctrl> + PPrevious history item
<ctrl> + WDelete previous word
<ctrl> + <delete>Delete next word
<alt> + <righ arrow>Move the cursor forward one word
<alt> + <left arrow>Move the cursor back one word
<ctrl> + RSearch backward in the history
<up arrow>Next history item
<down arrow>Previous history item

Note: on a mac keyboard, what we call <delete> is <suppr> and can be done pressing <fn> + <delete>