Start free trial

File Object

Updated 2 May 2026 MaSH

The File Object

In MaSH a File object represents a file or folder. Information about the file or folder is contained in the file object’s properties.

Properties

contents

contents: string|array get

File The full bytes of the file. Calls read.

Folder An array containing File objects representing the folder’s direct sub-items.

cursor

cursor: number get

File The current cursor position in bytes inside the file.

Folder N/A

deleted

deleted: boolean get

true if the File object has been deleted during execution of the script. false otherwise.

end

end: boolean get

File Indicates whether the cursor is at the end of the file. Useful to check whether the whole file has been read.

Folder N/A

extension

extension: string get

The extension component of the File’s name.

### isDir

isDir: boolean get

True if the File object is a directory/folder, False if it’s a file.

line

line: string get

File Read a line from the file from the current pointer position. Calls readLine().

Folder N/A

### mimetype

mimetype: string get

File The nature and format of the document. MIME types are defined and standardized in IETF’s RFC 6838.

Folder N/A

modified

modified: date get

The date that the file was created or last modified returned as a date object.

name

name: string get/set

The name of the file or folder. When set it calls rename.

nicePath

nicePath: string get

For storage adapters that use ID-based file paths this represents the human-readable version of the path.

path

path: string get

The path from the root of the Foldr share to the file or folder using / as a path separator.

size

size: number get

The size of the file in bytes.

share

share: share get

The share model representing the storage location that hosts the file.

stream

stream: resource get

File The raw data stream of the file.

Folder N/A

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline myFile.name
printline myFile.path
printline myFile.size
printline myFile.modified
printline myFile.mimetype

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline(myFile.name)
printline(myFile.path)
printline(myFile.size)
printline(myFile.modified)
printline(myFile.mimetype)

Output

file.txt
path/to/file.txt
30
2017-04-19 16:27:00
text/plain

Methods

delete

delete() -> void

Permanently remove a file or folder from the storage location.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

myFile.delete()

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

myFile.delete()

duplicate

duplicate(File|string: ?where) -> File

Create a copy of a file or folder and its contents.

Parameters

where

The location for the duplicated file to be created.

If no parameter is provided the File is duplicated inside its current folder and a new name is calculated.

If a directory File object is provided as the parameter then the file will be duplicated as a sub-item of the directory. A new name is calculated if there is a collision.

If a string is provided as the parameter then then the File is duplicated using the string as its path. Collisions will cause any existing files to be overwritten.

path

The path to the file using / as a path separator relative to the existing File object.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

set myDuplicate to myFile.duplicate()

printline myDuplicate

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

myDuplicate = myFile.duplicate()

printline(myDuplicate)

Output

File {
	"name": "file copy.txt",
	"path": "path/to/file.txt",
	"modified": "2022-02-01T12:35:00+01:00",
	"size": 30,
	"is_dir": false,
	"mimetype": "text/plain",
	"hidden": false,
	"extra": [],
	"share": {
		"id": 1,
		"name": "My Home Folder"
	}
}

get

get(string: path) -> File

Retrieves a sub-item using a path relative to its parent directory. Returns null if the item to be retrieved does not exist at the path provided.

Parameters

path

The path to the file using / as a path separator relative to the existing File object.

Natural

set root to mash.files.get(12, "", "b8236683-6426-4658-bf6f-0e78068ca327")

set subFile to root.get("path/to/file.txt")

printline subFile

Standard

root = mash.files.get(12, "", "b8236683-6426-4658-bf6f-0e78068ca327")

subFile = root.get("path/to/file.txt")

printline(subFile)

Output

File {
	"name": "file.txt",
	"path": "path/to/file.txt",
	"modified": "2021-06-09T10:00:01+01:00",
	"size": 30,
	"is_dir": false,
	"mimetype": "text/plain",
	"hidden": false,
	"extra": [],
	"share": {
		"id": 1,
		"name": "My Home Folder"
	}
}

in

in(File: parent) -> boolean

Checks whether a File object is a sub-item of the directory.

Parameters

parent

A File object representing a folder to be checked as to whether it contains the item.

Natural

root = mash.files.get(12, "path", "b8236683-6426-4658-bf6f-0e78068ca327")

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline myFile.in(root)

Standard

root = mash.files.get(12, "path", "b8236683-6426-4658-bf6f-0e78068ca327")

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline(myFile.in(root))

Output

true

make

make(string: path, boolean: ?isFolder = false, boolean: ?suggest = false) -> File

Create a new file or folder.

Parameters

path

The path to the file using / as a path separator relative to the existing File object.

isFolder

Whether the object that you are creating is a file or a folder. Set this parameter to true to create a folder. Default is false.

suggest

When set to true Foldr will not overwrite an existing file but will instead generate a unique name based on the existing contents of the target folder. Default is false.

Natural

set root to mash.files.get(12, "", "b8236683-6426-4658-bf6f-0e78068ca327")

set newFolder to root.make("New Folder", true)

printline newFolder

Standard

root = mash.files.get(12, "", "b8236683-6426-4658-bf6f-0e78068ca327")

newFolder = root.make("New Folder", true)

printline(newFolder)

Output

File {
	"name": "New Folder",
	"path": "New Folder",
	"modified": "2022-02-01T13:00:00+01:00",
	"size": 30,
	"is_dir": true,
	"mimetype": null,
	"hidden": false,
	"extra": [],
	"share": {
		"id": 1,
		"name": "My Home Folder"
	}
}

move

move(File|string: destination) -> File

Move a file or folder to a destination.

Parameters

destination

If the destination is a directory File object then the item will become a sub-item of the directory. If the destination is a string then the path must be relative to the root of the item’s current share and include the name of the file.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

set myDestination to mash.files.get(12, "path/to/destination", "b8236683-6426-4658-bf6f-0e78068ca327")

myFile.move(myDestination)

printline myFile

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

myDestination = mash.files.get(12, "path/to/destination", "b8236683-6426-4658-bf6f-0e78068ca327")

myFile.move(myDestination)

printline(myFile)

Output

File {
	"name": "file.txt",
	"path": "path/to/destination/file.txt",
	"modified": "2021-06-09T10:00:01+01:00",
	"size": 30,
	"is_dir": false,
	"mimetype": "text/plain",
	"hidden": false,
	"extra": [],
	"share": {
		"id": 1,
		"name": "My Home Folder"
	}
}

read

read(number: ?bytes) -> string

Read part or all of a file.

Parameters

bytes

The number of bytes of the file to read starting from the current cursor position. If no parameter is provided then the whole file will be read. The cursor will be advanced by the number of bytes read.

Notes

If the bytes parameter is provided then the read method will read from the current position of the file cursor. If no parameter is provided then the whole file will be read regardless of the position of the file cursor. Reading will stop if the end of the file is reached regardless of the number of bytes requested.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

# This will print the first 5 characters of the file.

printline myFile.read(5)

# The file cursor will then be at position 5.

printline myFile.cursor

# This will print the whole file regardless of the position of the file cursor. The cursor position will not change.

printline myFile.read()

# This will read the final 6 characters of the file

printline myFile.read(6)

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

# This will print the first 5 characters of the file.

printline(myFile.read(5))

# The file cursor will then be at position 5.

printline(myFile.cursor)

# This will print the whole file regardless of the position of the file cursor. The cursor position will not change.

printline(myFile.read())

# This will read the final 6 characters of the file

printline(myFile.read(6))

Output

Hello
5
Hello World
 World

readline

readline() -> string

Read to the next newline character or the end of the file from the current cursor position. The cursor will be advanced by the number of bytes read.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline myFile.readLine()

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline(myFile.readLine())

Output

Hello World

rename

rename(string: newName) -> File

Change the name of a file or folder.

Parameters

newName

The new name of the file or folder relative to its current path.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

myFile.rename("file renamed.txt")

printline myFile

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

myFile.rename("file renamed.txt")

printline(myFile)

Output

File {
	"name": "file renamed.txt",
	"path": "path/to/file renamed.txt",
	"modified": "2021-06-09T10:00:01+01:00",
	"size": 30,
	"is_dir": false,
	"mimetype": "text/plain",
	"hidden": false,
	"extra": [],
	"share": {
		"id": 1,
		"name": "My Home Folder"
	}
}

rewind

rewind()

Move the file cursor to the beginning of the file.

refresh

refresh()

Refresh a File’s metadata from the storage location. Useful when the underlying file may change outside of MaSH/Foldr.

seek

seek(number: position)

Set the File cursor to the specified position. The start of a file is cursor position 0.

Parameters

position

The position within the file to set the cursor to starting from 0.

tell

tell() -> number

Returns the position of the cursor within the File. The start of a file is cursor position 0.

write

File write(mixed: data)

Write to a file object

Parameters

data

The information to be written to the file. This can either be a string, another file’s stream or most native MaSH objects.

Folder write(string name, mixed data, boolean ?overwrite = true) -> File

Write to a sub-item of a folder.

Parameters

name

The name of the file to be written.

data

The information to be written to the file. This can either be a string, another file’s stream or most native MaSH objects.

overwrite

By default any file with named name that exists in the folder will be overwritten. Set this to false and MaSH will generate a unique filename based on the supplied name and the existing folder contents.

Natural

set myFile to mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline myFile.read()

myFile.write("Hello from mash")

printline myFile.read()

set myFolder to mash.files.get(12, "path/to", "b8236683-6426-4658-bf6f-0e78068ca327")

set newFile to myFolder.write("new file.txt", "Hello again from mash")

printline newFile.name

printline newFile.read()

Standard

myFile = mash.files.get(12, "path/to/file.txt", "b8236683-6426-4658-bf6f-0e78068ca327")

printline(myFile.read())

myFile.write("Hello from mash")

printline(myFile.read())

myFolder = mash.files.get(12, "path/to", "b8236683-6426-4658-bf6f-0e78068ca327")

newFile = myFolder.write("new file.txt", "Hello again from mash")

printline(newFile.name)

printline(newFile.read())

Output

Hello world
Hello from mash
new file.txt
Hello again from mash

Notes

You can pass MaSH csv, image, pdf, xml and xlsx objects in as the data parameter and they will be automatically converted to a suitable format for writing.

← All articles