File

File · Type

A File is anything on a share: a document, an image or a folder. You get one from mash.files.get, from mash.event.file, from a folder’s contents or parent, and from search results. Once you hold one, it’s the thing you read, change, copy, move and tag.

How it works

A folder is a File too. Check is_dir to tell them apart. A folder lists what’s inside it with contents. A document gives its bytes with contents, so the same word means “the list” on one and “the data” on the other.

It was opened as someone. Each File remembers the user it was opened as, and that decides what its permissions, sharing and activity log act as. A file you take from mash.event.file is opened as the event’s user. A file from a folder’s contents or make carries its parent’s user.

What it knows. The properties you’ll use most are name, display_name (no extension), extension, path, nice_path, size, modified (a date), mimetype, is_dir, share, parent, fields and contents.

Changing a name or date is a write. Setting file.name renames the file. Setting file.modified changes its modified date. Everything else is read-only, and assigning to it is an error.

Writes check permissions. write, make, rename, move, duplicate and delete each check the write permission of whoever the script runs as. They fail with a permission error if it’s missing. A move or copy across shares checks the destination as well.

Common tasks

Read a property and the text inside a file:

set doc to mash.files.get("Orders", "Inbox/note.txt")
printline "{{doc.name}}: {{doc.size}} bytes, changed {{doc.modified.format('d M Y')}}"
printline doc.contents

Go through a folder, newest first:

set folder to mash.files.get("Orders", "Inbox")
set files to mash.collect(folder.contents).where("is_dir", false).sortByDesc("modified")
each files as f
    printline "{{f.name}} {{f.modified.format('Y-m-d')}}"
end

Create a folder (safe to repeat) and put a file in it:

set root to mash.files.get("Orders", "")
set month to root.make("2026-11", true)
month.write("summary.txt", "Done")

File it away without losing the original until you’re sure:

set doc to mash.files.get("Orders", "Inbox/despatch-1182.pdf")
set archive to mash.files.get("Orders", "Archive/2026")
set copy to doc.duplicate(archive)
printline "Copied to {{copy.path}}"

Read and write custom fields through fields. A field with nothing in it reads as null, and a multivalue field reads as a Collection:

set doc to mash.files.get("Orders", "Inbox/despatch-1182.pdf")
set status to doc.fields["Status"] ?? "New"
doc.fields.set("Status", "Ordered")
doc.fields.set("Party", "Acme Ltd", {action: "add"})

Watch out for

• A folder’s write(name, data) overwrites a file of that name by default. Its optional third argument is the overwrite flag. Pass false when you don’t want that.
• Folders have no custom fields. fields.set on a folder is an error.
• Treat delete() as permanent unless you know the share keeps a recycle bin. Develop with duplicate, then switch to delete once the script is right.
• A script that writes into the share that triggers it runs again. See Reacting to events.
• Sizes are bytes. A folder’s size is 0.
• a.is(b) compares address, size and modified date. It says whether two Files are the same item in the same state, so a file that has changed since you opened it is no longer is its earlier self.

See also

Files and folders and Custom fields in the tutorial. The mash.files object finds files. mash.csv, mash.xlsx and mash.pdf read them.

Class File

Properties

Name	Type	Description
basename	string	The last part of the path.
deleted	bool	True when it has been deleted.
dirname	string	The path of the folder that holds it.
display_name	string	The name without its extension.
events	bool	Whether changes made through this file raise Foldr events. Assign false to stop them.
extension	string	The extension without the dot, or an empty string.
hidden	bool	True when the storage marks it hidden.
is_dir	bool	True for a folder, false for a file.
is_moved	bool	True when this event moved or renamed it.
is_new	bool	True when this event created it.
is_updated	bool	True when this event changed it.
mimetype	string	The MIME type, such as application/pdf. A folder has none.
modified	Date	When it was last changed. Assigning a date sets it on storage that allows that.
name	string	The name with its extension. Assigning a new string renames the file or folder.
nice_path	string	The path as people see it in Foldr. It differs from path only on storage whose own paths are not readable (an id-based store, say).
nice_uri	string	The same address built from nice_path.
parent	Folder	The folder that holds it, or null at the top of the share.
path	string	The path inside the share.
share	Share	The share it lives on.
size	int	The size in bytes. A folder is 0.
uri	string	The share and the path together, as one address.
user	User	The account it was opened as.
vendor_id	string	The id the storage gives it (Google Drive, OneDrive, Box and similar), when it has one.

Methods

childrenComplete

file.childrenComplete() → bool

No description yet.

delete

file.delete()

No description yet.

duplicate

file.duplicate(destination?: File, sourceVersion?: string)

No description yet.

getName

file.getName() → string

No description yet.

getParent

file.getParent() → File

No description yet.

getPath

file.getPath() → string

No description yet.

getShare

file.getShare() → Share

No description yet.

getUser

file.getUser() → User

No description yet.

hasStatus

file.hasStatus(status: FileStatus) → bool

No description yet.

in

file.in(folders?: File) → bool

No description yet.

is

file.is(file: File) → bool

No description yet.

isDeleted

file.isDeleted() → bool

No description yet.

isDir

file.isDir() → bool

No description yet.

isMoved

file.isMoved() → bool

No description yet.

isNew

file.isNew() → bool

No description yet.

isUpdated

file.isUpdated() → bool

No description yet.

make

file.make(path: Stringable, asDir?: bool = false, suggest?: bool = false, force?: bool = false) → File

No description yet.

move

file.move(destination: Folder, suggest?: bool = false) → bool

No description yet.

refresh

file.refresh()

No description yet.

release

file.release()

No description yet.

rename

file.rename(newName: string) → bool

No description yet.

reserve

file.reserve(ttl?: mixed = 10)

No description yet.

setUser

file.setUser(user?: mixed)

The user this file is opened as: what sharing, permissions and activity act as. Takes a user, a MaSH user (file.setUser(owner)) or a GUID; null clears it. A script giving an event file a user so it can share it is the case this is called from MaSH for.

triggerEvents

file.triggerEvents()

No description yet.