Skip to content

Getting started

Documentation - Version Beta

Table of contents

Builtins
- cat
- cd
- chmod
- chown
- grep
- ls
- mkdir
- mv
- pwd
- $ (execute)
- stat
- source
- touch
Commands
- npm
Shortcuts

Table of contents

Builtins
- cat
- cd
- chmod
- chown
- grep
- ls
- mkdir
- mv
- pwd
- $ (execute)
- stat
- source
- touch
Commands
- npm
Shortcuts

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): any

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): any

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

Returns the permissions of the itemPath item.

chmod.add.read(itemPath): any

Adds read permission to user, group and others.

Returns the permissions of the itemPath item.

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

Adds read permission to user.

Returns the permissions of the itemPath item.

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

Adds read permission to group.

Returns the permissions of the itemPath item.

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

Adds read permission to others.

Returns the permissions of the itemPath item.

chmod.add.write(itemPath): any

Adds write permission to user, group and others.

Returns the permissions of the itemPath item.

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

Adds write permission to user.

Returns the permissions of the itemPath item.

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

Adds write permission to group.

Returns the permissions of the itemPath item.

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

Adds write permission to others.

Returns the permissions of the itemPath item.

chmod.add.execute(itemPath): any

Adds execution permission to user, group and others.

Returns the permissions of the itemPath item.

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

Adds execution permission to user, group and others.

Returns the permissions of the itemPath item.

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

Adds execution permission to group.

Returns the permissions of the itemPath item.

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

Adds execution permission to others.

Returns the permissions of the itemPath item.

chmod.remove(itemPath): any

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

Returns the permissions of the itemPath item.

chmod.remove.read(itemPath): any

Removes read permission to user, group and others.

Returns the permissions of the itemPath item.

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

Removes read permission to user.

Returns the permissions of the itemPath item.

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

Removes read permission to group.

Returns the permissions of the itemPath item.

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

Removes read permission to others.

Returns the permissions of the itemPath item.

chmod.remove.write(itemPath): any

Removes write permission to user, group and others.

Returns the permissions of the itemPath item.

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

Removes write permission to user.

Returns the permissions of the itemPath item.

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

Removes write permission to group.

Returns the permissions of the itemPath item.

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

Removes write permission to others.

Returns the permissions of the itemPath item.

chmod.remove.execute(itemPath): any

Removes execution permission to user, group and others.

Returns the permissions of the itemPath item.

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

Removes execution permission to user, group and others.

Returns the permissions of the itemPath item.

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

Removes execution permission to group.

Returns the permissions of the itemPath item.

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

Removes execution permission to others.

Returns the permissions of the itemPath item.

chmod.set(itemPath, perm): any

Sets perm permissions.

Returns the permissions of the itemPath item.

chmod.set.read(itemPath): any

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): any

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

Returns the permissions of the itemPath item.

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

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

Returns the permissions of the itemPath item.

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

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

Returns the permissions of the itemPath item.

chmod.set.write(itemPath): any

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): any

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

Returns the permissions of the itemPath item.

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

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

Returns the permissions of the itemPath item.

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

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

Returns the permissions of the itemPath item.

chmod.set.execute(itemPath): any

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): any

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): any

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

Returns the permissions of the itemPath item.

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

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

Returns the permissions of the itemPath item.

chown

Not available on Windows.

chown(itemPath): any

Returns the owner and group of the itemPath item.

Example:

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

chown.get(itemPath): any

Alias to chown().

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

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): any

Set the owner of the itemPath item with username.

Returns the owner and group of the itemPath item.

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

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.intermediate(dirpath: string): string

Synchronously creates a directory and the intermediate directories if necessary.

Returns the dirpath of the created directory.

Example:

mkdir.intermediate('dirs/that/do/not/exist')

mv

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

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): any

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'
  }

source

source(moduleName): any

Reads and executes the content of a JavaScript file or JavaScript module. It uses require under the hood without cache with a custom resolution. The resolution follows this order:

resolve core module (like path)
resolve the current working directory. Use pwd() to get the current working directory.
resolve the $NODE_PATH environment variable. The variable is set to a colon-delimited (:) list of absolute paths for non Windows system and semicolons (;) for Windows system.
resolve the User home ($HOME for non Windows system / %USERPROFILE% for Windows system) following sub-directories: 1. node_modules 2. node_libraries 3. node_packages.
resolve the $NODE_MODULES environment variable. The variable is set to a colon-delimited (:) list of absolute paths for non Windows system and semicolons (;) for Windows system.
resolve global location based on the node installation path. Returns the exported module content.

Example of file execution:

> source('helloWorld.js')
"Hello World!"

Example of module importation:

> l = npm.install('lodash')
...
> l.random();

source.resolve(moduleName): string

Use the internal source mechanism to look up the location of the given module, but rather than loading the module, it just returns the resolved filepath.

Returns the filepath of the found module.

Example:

> source.resolve('chalk')
'/Users/arnauddebec/Dev/nacre/node_modules/chalk/source/index.js'

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.

Shortcut	Description
`<ctrl> + C`	Quit Nacre / Remove the current line
`<ctrl> + H`	Delete previous character
`<ctrl> + U`	Delete from the current cursor to the line start
`<ctrl> + K`	Delete from the current cursor to the line end
`<ctrl> + A`	Move the cursor to the begining of the line
`<ctrl> + E`	Move the cursor to the end of the line
`<ctrl> + B`	Move the cursor back one character
`<ctrl> + F`	Move the cursor forward one character
`<ctrl> + L`	Clear the screen of the terminal
`<ctrl> + N`	Next history item
`<ctrl> + P`	Previous history item
`<ctrl> + W`	Delete 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> + R`	Search 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>