File functions
These functions can be used to work with files.
Available since: v3.0.0
file::bucket
API DEFINITION
file::bucket(file) -> string
The file::bucket function returns the name of the bucket in which a file is located.
file::bucket(f"my_bucket:/file_name");
DEFINE PARAM $SOME_DATABASE_FILE VALUE f"my_bucket:/file_name";
file::bucket($SOME_DATABASE_FILE);
Output
'my_bucket'
The counterpart to this function is file::key, which returns the latter part of a file pointer.
file::copy
The file::copy function copies the contents of a file to a new file, overwriting any existing file that has the same name as the new file.
API DEFINITION
file::copy(string)
Example of a file my_book.txt being copied to a new location lion_witch_wardrobe.txt:
f"my_bucket:/my_book.txt".copy("lion_witch_wardrobe.txt");
file::copy_if_not_exists
The file::copy_if_not_exists function copies the contents of a file to a new file, returning an error if a file already exists that has the same name as that of the intended copy.
API DEFINITION
file::copy_if_not_exists(string)
Example of a file my_book.txt attempting to copy to a new location lion_witch_wardrobe.txt:
DEFINE BUCKET my_bucket BACKEND "memory";
f"my_bucket:/lion_witch_wardrobe.txt".put("Once there were four children whose names were Peter, Susan...");
f"my_bucket:/other_book.txt".put("Um meine Geschichte zu erzählen, muß ich weit vorn anfangen.");
f"my_bucket:/other_book.txt".copy_if_not_exists("lion_witch_wardrobe.txt");
Output
'Operation for bucket `my_bucket` failed: Object at location lion_witch_wardrobe.txt already exists:
Object already exists at that location: lion_witch_wardrobe.txt'
file::delete
The file::delete function deletes a file.
API DEFINITION
file::delete(string)
Example of a file my_book.txt being deleted:
f"my_bucket:/my_book.txt".delete();
file::exists
The file::exists function checks to see if a file exists at the path and file name indicated.
API DEFINITION
file::exists(string) -> bool
Example of an IF else STATEMENT used to check if a file exists before writing content to the location:
IF f"my_bucket:/my_book.txt".exists() {
THROW "Whoops, already there!"
} ELSE {
f"my_bucket:/my_book.txt".put("Some content")
};
file::get
The file::get function retrieves a file for use.
API DEFINITION
file::get(string) -> bytes
A retrieved file will display as bytes. If valid text, these can be cast into a string.
f"my_bucket:/my_book.txt".get();
<string>f"my_bucket:/my_book.txt".get();
Output
b"536F6D6520636F6E74656E74"
'Once there were four children whose names were Peter, Susan...'
file::head
The file::head function returns the metadata for a file.
API DEFINITION
file::head() -> object
If a file is found, the metadata will be returned as an object with the following fields:
e_data (option<string>): the unique identifier for the file.last_modified (datetime)location (string)size (int)version (option<string>)
An example of this function and its output:
f"my_bucket:/my_book.txt".head();
Output
{
e_tag: '1',
key: 'my_book.txt',
last_modified: d'2025-03-26T06:29:18.988Z',
size: 78,
version: NONE
}
file::key
API DEFINITION
file::key(file) -> string
The file::key function returns the key of a file: the part of a file pointer following the bucket name.
file::key(f"my_bucket:/file_name");
DEFINE PARAM $SOME_DATABASE_FILE VALUE f"my_bucket:/file_name";
file::key($SOME_DATABASE_FILE);
Output
'/file_name'
The counterpart to this function is file::bucket, which returns the bucket name of a file pointer.
file::list
API DEFINITION
file::list(string, $list_options: option<object>) -> array<object>
The file::list returns the metadata for the files inside a certain bucket. The output is an array of objects, each containing the following fields:
file: the pointer to the file.size (int): the file size in bytes.updated (datetime): the last time a change was made to the file.
DEFINE BUCKET my_bucket BACKEND "memory";
f"my_bucket:/some_book".put("Once upon a time...");
f"my_bucket:/some_book".rename("awesome_book");
f"my_bucket:/some_book".put("In a hole in the ground lived a Hobbit.");
file::list("my_bucket");
Output
[
{
file: f"my_bucket:/awesome_book",
size: 19,
updated: d'2025-04-08T03:28:20.530511Z'
},
{
file: f"my_bucket:/some_book",
size: 39,
updated: d'2025-04-08T03:28:20.530704Z'
}
]
To modify the output, a second argument can be passed in that contains a single object with up to three fields:
limit (int): the maximum number of files to display.start (string): displays files ordered after start.prefix (string): displays files whose names begin with prefix.
Some examples of the function containing the second object and their responses:
file::list("my_bucket", { limit: 1 });
file::list("my_bucket", { limit: 0 });
Output
[
{
file: f"my_bucket:/awesome_book",
size: 19,
updated: d'2025-04-15T05:35:40.913221Z'
}
]
[]
file::list("my_bucket", { prefix: "some" });
file::list("my_bucket", { prefix: "someBOOOEOEOK" });
Output
[
{
file: f"my_bucket:/some_book",
size: 39,
updated: d'2025-04-15T05:35:40.913554Z'
}
]
[]
file::list("my_bucket", { start: "a" });
file::list("my_bucket", { start: "m" });
Output
[
{
file: f"my_bucket:/awesome_book",
size: 19,
updated: d'2025-04-15T05:55:41.973869Z'
},
{
file: f"my_bucket:/some_book",
size: 39,
updated: d'2025-04-15T05:55:41.974370Z'
}
]
[
{
file: f"my_bucket:/some_book",
size: 39,
updated: d'2025-04-15T05:55:41.974370Z'
}
]
file::list("my_bucket", { prefix: "some", start: "a", limit: 1 });
Output
[
{
file: f"my_bucket:/some_book",
size: 39,
updated: d'2025-04-15T05:35:40.913554Z'
}
]
file::put
The file::put function adds data into a file, overwriting any existing data.
API DEFINITION
file::put()
An example of this function followed by file::get() to display the contents:
DEFINE BUCKET my_bucket BACKEND "memory";
f"my_bucket:/my_book.txt".put("Once there were four children whose names were Peter, Susan...");
f"my_bucket:/my_book.txt".put("Or were there? I don't quite remember.");
<string>f"my_bucket:/my_book.txt".get();
Output
"Or were there? I don't quite remember."
file::put_if_not_exists
The file::put function adds data into a file, unless a file of the same name already exists.
API DEFINITION
file::put_if_not_exists()
An example of this function followed by file::get() to display the contents:
DEFINE BUCKET my_bucket BACKEND "memory";
f"my_bucket:/my_book.txt".put_if_not_exists("Once there were four children whose names were Peter, Susan...");
f"my_bucket:/my_book.txt".put_if_not_exists("Or were there? I don't quite remember.");
<string>f"my_bucket:/my_book.txt".get();
Output
'Once there were four children whose names were Peter, Susan...'
file::rename
The file::rename function renames a file, overwriting any existing file that has the same name as the target name.
API DEFINITION
file::rename()
An example of a file being renamed over an existing file:
DEFINE BUCKET my_bucket BACKEND "memory";
f"my_bucket:/my_book.txt".put("Once there were four children whose names were Peter, Susan...");
f"my_bucket:/other_book.txt".put("Or were there? I don't quite remember.");
f"my_bucket:/other_book.txt".rename("my_book.txt");
<string>f"my_bucket:/my_book.txt".get();
Output
"Or were there? I don't quite remember."
file::rename_if_not_exists
The file::rename_if_not_exists function renames a file, returning an error if a file already exists that has the same name as the target name.
API DEFINITION
file::rename_if_not_exists()
Output
'Operation for bucket `my_bucket` failed: Object at location my_book.txt already exists:
Object already exists at that location: my_book.txt'
'Once there were four children whose names were Peter, Susan...
