Filesystem

Each Loop is provided with their own blank "working" directory for this Aptitude, which is what relative paths resolve to. Loops are free to do anything they want to any file/directory inside of this working directory.
Loops cannot access other Loops' working directories.
This working directory persists across Loop version updates.
API
Example
Permissions
Copy
Copies a file from one location to another.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
const SOURCE_PATH = '/var/log/system.log';
4
const DESTINATION_PATH = '/Users/username/system.log';
5
​
6
// Check to make sure the system log exists
7
const systemLogExists = await filesystem.exists(SOURCE_PATH);
8
​
9
// Copy the system log to the user folder
10
if (systemLogExists) {
11
    await filesystem.copy(SOURCE_PATH, DESTINATION_PATH);
12
}
Copied!
dir
Returns all files in the specified directory.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// Get all files in the /var/log directory
4
const allLogs = await filesystem.dir('/var/log');
5
​
6
/*
7
allLogs:
8
[
9
  {
10
    "name": "foo.txt",
11
    "size": 476,
12
    "mode": "-rw-r--r--",
13
    "modTime": "2021-10-18T12:46:16.234535644-04:00",
14
    "isDir": false
15
  },
16
  {
17
    "name": "bar",
18
    "size": 96,
19
    "mode": "drwxr-xr-x",
20
    "modTime": "2021-09-19T05:25:54.491321266-04:00",
21
    "isDir": true
22
  },
23
  ...
24
]
25
*/
Copied!
exists
Return true if a file or directory exists at the specified location.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// Check to make sure /var/log directory exists
4
const logDirExists = await filesystem.exists('/var/log');
5
// logDirExists === true
6
​
7
// Check to make sure /var/log/system.log file exists
8
const sysLogExists = await filesystem.exists('/var/log/system.log');
9
// sysLogExists === true
10
​
11
// Check to make sure /var/log/fakeDirectory directory exists
12
const fakeDirExists = await filesystem.exists('/var/log/fakeDirectory');
13
// fakeDirExists === false
Copied!
join
Join joins an array of path elements into a single path, separating them with an OS specific Separator. Empty elements are ignored. The result is cleaned. However, if the argument list is empty or all its elements are empty, Join returns an empty string. On Windows, the result will only be a UNC path if the first non-empty element is a UNC path.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// Create path string for a local text file that works on both 
4
// Windows and Unix-based systems
5
const testDirectory = await filesystem.join(['testDirectory', 'foo.txt']);
6
// Windows: testDirectory == testDirectory\foo.txt
7
// macOS: testDirectory == testDirectory/foo.txt
Copied!
listenDir
Listen for changes to the contents of the directory.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// The path of the directory where we want to listen for changes
4
const PATH = '/var/log';
5
// The callback function that runs when a change is detected
6
const callback = (fileEvent) => {
7
    // When a file or directory are added, opened, or updated:
8
    /*
9
    fileEvent:
10
    {
11
      "info": {
12
        "name": "foo.log",
13
        "size": 17,
14
        "mode": "-rwxr-xr-x",
15
        "modTime": "2021-10-27T22:14:24.596962-04:00",
16
        "isDir": false
17
      },
18
      "action": "Create" or "Chmod"
19
    }
20
    */
21
    
22
    // When a file or directory is renamed or removed, it will fire off 
23
    // the above fileEvent then another one afterward:
24
    /*
25
    fileEvent:
26
    {
27
      "action": "Rename" or "Remove",
28
      "name": "test.log" // old file name
29
    }
30
    */
31
}
32
​
33
const directoryListener = await filesystem.listenDir(PATH, callback);
34
​
35
// Cancel the listener
36
directoryListen.cancel();
Copied!
listenFile
Listen for changes to a specific file.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// The path of the file we want to listen to for changes
4
const PATH = '/var/log/system.log';
5
// The callback function that runs when a change is detected
6
const callback = (fileEvent) => {
7
    // When the file is opened or updated:
8
    /*
9
    fileEvent:
10
    {
11
      "info": {
12
        "name": "system.log",
13
        "size": 14592,
14
        "mode": "-rwxr-xr-x",
15
        "modTime": "2021-10-27T22:31:24.215811-04:00",
16
        "isDir": false
17
      },
18
      "action": "Chmod"
19
    }
20
    */
21
    
22
    // When the file is renamed or removed, it will fire off 
23
    // the above fileEvent then another one afterward:
24
    /*
25
    fileEvent:
26
    {
27
      "action": "Rename" or "Remove",
28
      "name": "system.log" // old file name
29
    }
30
    */
31
}
32
​
33
const fileListener = await filesystem.listenFile(PATH, callback);
34
​
35
// Cancel the listener
36
fileListener.cancel();
Copied!
makeDir
Makes a directory at the specified location.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// The path of the directory we want to create
4
const DESTINATION_PATH = '/var/log/backups';
5
​
6
// The permissions we want to give the directory, in octal format
7
// https://www.linode.com/docs/guides/modify-file-permissions-with-chmod/
8
const WRITE_MODE = 0o750
9
​
10
// Check to make sure the directory doesn't already exist
11
const directoryExists = await filesystem.exists(DESTINATION_PATH);
12
​
13
if (!directoryExists) {
14
    await filesystem.makeDir(DESTINATION_PATH, WRITE_MODE);
15
}
Copied!
move
Moves a file from one location to another.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
const SOURCE_PATH = '/var/log/system.log';
4
const DESTINATION_PATH = '/Users/username/system.log';
5
​
6
// Check to make sure the system log exists
7
const systemLogExists = await filesystem.exists(SOURCE_PATH);
8
​
9
// Move the system log to the user folder
10
await filesystem.move(SOURCE_PATH, DESTINATION_PATH);
Copied!
openWithDefaultApplication
Opens a file using the operating system's default tool for the extension provided in the path parameter, including directories.
Limited to the following file extensions: .txt, .xls, .xlsx, .csv, .pdf, .doc, .docx, .jpg, .jpeg, .png, .apng, .gif, .tif, .tiff, .bmp, .webp, .svg, and .ico
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// Open foo.txt in the loop directory
4
await filesystem.openWithDefaultApplication('foo.txt')
Copied!
readFile
Returns the contents of the specified file.
1
import { filesystem, network } from '@oliveai/ldk';
2
​
3
// Path of the system log that we want to read
4
const FILE_PATH = '/var/log/system.log';
5
​
6
// Get the contents of the system log, returned as a Uint8Array
7
const encodedSysLog = await filesystem.readFile(FILE_PATH);
8
​
9
// Decode the contents to get the actual string value
10
const decodedSysLog = await network.decode(encodedSysLog);
11
​
12
// decodedSysLog === human readable string of system.log contents
Copied!
remove
Removes a file/directory at the specified path.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// Path of foo.txt in the local loop directory
4
const FILE_PATH = 'foo.txt';
5
​
6
// Delete foo.txt
7
await filesystem.remove(FILE_PATH);
Copied!
stat
Returns info about a specified file/directory.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
const DIRECTORY_PATH = '/var/log';
4
const FILE_PATH = '/var/log/system.log';
5
​
6
const directoryInfo = await filesystem.stat(DIRECTORY_PATH);
7
/*
8
directoryInfo:
9
{
10
  "name": "log",
11
  "size": 1408,
12
  "mode": "drwxr-xr-x",
13
  "modTime": "2021-10-28T01:01:11.003025289-04:00",
14
  "isDir": true
15
}
16
*/
17
​
18
const fileInfo = await filesystem.stat(FILE_PATH);
19
/*
20
system.log:
21
{
22
  "name": "system.log",
23
  "size": 353232,
24
  "mode": "-rw-r-----",
25
  "modTime": "2021-10-28T12:29:25.305970009-04:00",
26
  "isDir": false
27
}
28
*/
Copied!
unzip
Unzips sourced file to a specified directory.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// foo.zip is in the local loop directory, and contains bar.txt
4
// Unzip the contents of foo.zip to the directory "baz"
5
await filesystem.unzip('foo.zip', 'baz');
6
​
7
const unzipSuccessful = await filesystem.exists('baz/bar.txt');
8
// unzipSuccessful === true
Copied!
workDir
Get the Loop's working directory.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// Get the full path to the loop's working directory
4
const loopPath = await filesystem.workDir();
5
​
6
// macOS: loopPath === /Users/username/Library/Application Support/Olive Helps/secureloopWork/123456-unique-loop-id
7
// Windows: loopPath === C:\Users\username\AppData\Roaming\Olive Helps\secureloopWork\123456-unique-loop-id
Copied!
writeFile
WriteFile writes data to a file and is designed for both synchronous and asynchronous operation.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// The content we'll be putting in the file
4
const FILE_CONTENT = 'Some test text to put in a file';
5
​
6
// The path in the loop directory for the file
7
const DIRECTORY = 'foo';
8
const FILE_NAME = 'bar.txt';
9
const filePath = await filesystem.join([DIRECTORY, FILE_NAME]);
10
​
11
// The permissions we want to give the file, in octal format
12
// https://www.linode.com/docs/guides/modify-file-permissions-with-chmod/
13
const FILE_PERMISSIONS = 0o750;
14
​
15
// The write operations to choose from while writing the file
16
const { overwrite, append } = filesystem.WriteOperation;
17
​
18
const writeFileParams = {
19
    data: FILE_CONTENT,
20
    path: filePath,
21
    writeMode: FILE_PERMISSIONS,
22
    writeOperation: overwrite
23
};
24
​
25
await filesystem.writeFile(writeFileParams);
Copied!
In this example, we use the Clipboard aptitude to listen for you copying text to the clipboard, and automatically append it to a file in the local Loop directory. This could be useful to pair with a button/toggle in a Whisper, where this capability can be enabled before rapidly copying several items, pasted into the file, then toggle it off when finished.
1
import { filesystem, clipboard } from '@oliveai/ldk';
2
​
3
const FILE_NAME = 'clipboardPastes.txt';
4
const baseWriteFileParams = {
5
    data: '',
6
    path: FILE_NAME,
7
    writeMode: 0o755,
8
    writeOperation: filesystem.WriteOperation.append,
9
};
10
​
11
// Include clipboard events that happen while the 
12
// Olive Helps window is in focus
13
const INCLUDE_OLIVE_HELPS_EVENTS = true;
14
​
15
clipboard.listen(INCLUDE_OLIVE_HELPS_EVENTS, (clipboardText) => {
16
    const writeFileParams = {
17
        ...baseWriteFileParams,
18
        data: clipboardText + '\n',
19
    };
20
​
21
    await filesystem.writeFile(writeFileParams);
22
});
Copied!
Listen to directory for zip files and automatically unzip then delete zip file. This could be customized with the Dropzone component to select the exact folder to monitor for ZIP files.
1
import { filesystem } from '@oliveai/ldk';
2
​
3
// Here we're declaring the downloads folder, but this can be chosen by the
4
// user using the Dropzone component in a Whisper
5
const downloadsFolder = '/Users/username/Downloads';
6
​
7
filesystem.listenDir(downloadsFolder, async (fileEvent) => {
8
    const { action, info } = fileEvent;
9
​
10
    // If a file was "created" in this directory
11
    if (action === 'Create' && info) {
12
        const { name: fileName } = info;
13
​
14
        // If the file is a zip file, unzip it
15
        if (fileName.endsWith('.zip')) {
16
            const zipFilePath = await filesystem.join([downloadsFolder, fileName]);
17
​
18
            // Unzip the contents to the Downloads folder
19
            await filesystem.unzip(zipFilePath, downloadsFolder);
20
​
21
            // Delete the zip file after unzipping
22
            await filesystem.remove(zipFilePath);
23
        }
24
    }
25
});
Copied!
To use the Filesystem Aptitude, use the following permissions outline in your package.json under the ldk object.
​
Please see our Permissions page for more information.
​
1
...
2
"ldk": {
3
  "permissions": {
4
    "filesystem": {
5
      "pathGlobs": [
6
        {
7
          "value": "string"
8
        },
9
        ...
10
      ]
11
    },
12
    ...
13
  }
14
},
15
...
Copied!
Each value can either refer to an exact absolute path or use a glob wildcard. The only supported wildcards are ** and *, and can be used anywhere in the path.
Relative file paths can be accessed without specifying them in the permissions list.
Examples
1
{
2
  "ldk": {
3
    "permissions": {
4
      "filesystem": {
5
        "pathGlobs": [
6
          {
7
            // Provides access to all files in the /tmp directory that have a .txt extension.
8
            "value": "/tmp/*.txt"
9
          },
10
          {
11
            // Provides access to all directories and files under the /tmp directory.
12
            "value": "/tmp/**"
13
          },
14
          {
15
            // Provides access to all files with .txt extensions in the /tmp directory or any of its subdirectories.
16
            "value": "/tmp/**/*.txt"
17
          },
18
          {
19
            // Provides access to all files with .txt extensions in any subdirectory of /tmp.
20
            "value": "/tmp/*/*.txt"
21
          }
22
        ]
23
      }
24
    }
25
  }
26
}
Copied!
APTITUDES - Previous
Document
Next - APTITUDES
Keyboard
Last modified 5d ago
Copy link