Files

mash.files · Files & Storage

mash.files is how a script gets hold of a file or folder on a share. Everything else you do with files (read, write, copy, move, set fields, share) happens on the object it gives you, which is a File. Use mash.files to look things up and to check whether they’re there. Use the File to do the work.

How it works

A file is opened as someone. mash.files.get(share, path) opens the file as the person or automation running the script. The share’s own permissions decide what that run can read and change, and on an SMB share the storage’s permissions decide too. Pass a third argument, a user, to open the file as somebody else. A script written by a user (not an administrator) can only open files as its own owner, and passing anyone else is refused.

The share is a name, an id or a UUID. The path starts at the share’s root and uses /, with no leading slash. An empty path is the share’s root folder.

A missing file is an error, not null. get raises a “file not found” error when nothing is there. Check first with exists if absence is normal, or catch the error with an error block (see When things go wrong).

exists says yes or no. status says why. exists answers false only when the storage says the file isn’t there. If the share can’t be reached or the account is refused, exists records an error instead of answering false, so a script’s “create it if it isn’t there” can’t overwrite a file it simply couldn’t see. When you’re about to write where a file might be, ask status. It returns one of found, missing, refused or unreachable.

Common tasks

Test for a file, then open it:

if mash.files.exists("Finance", "Invoices/2026/INV-2041.pdf")
    set invoice to mash.files.get("Finance", "Invoices/2026/INV-2041.pdf")
    printline "{{invoice.name}} is {{invoice.size}} bytes"
end

Tell “not there” apart from “couldn’t look” before you create something:

set state to mash.files.status("Finance", "Reports/summary.csv")
if state is "missing"
    set folder to mash.files.get("Finance", "Reports")
    folder.write("summary.csv", "date,total")
elseif state is not "found"
    fail("Can't tell whether summary.csv exists: the share said {{state}}")
end

Pull path pieces apart without opening anything:

printline mash.files.basename("Invoices/2026/INV-2041.pdf")
printline mash.files.dirname("Invoices/2026/INV-2041.pdf")

INV-2041.pdf
Invoices/2026

Search a share (see mash.search for the options):

set hits to mash.files.search("Finance", "invoice AND 2026")
printline "{{hits.count()}} matches"

Watch out for

• Pass a folder object to copy, move and duplicate, not a text path. Text is read as a path on the file’s own share.
• mash.files.token(file) makes a web address that anyone who holds it can use to download that file. Treat it like a public link. A file blocked by Governance won’t get one.
• mash.files.events switches file events on or off for the script. Leave it on unless you’re sure writing a file shouldn’t trigger the scripts watching that share.
• Searching through mash.files.search is as accurate as the search index, which can be a little behind. For a value you’ve just written to a custom field, use mash.search.byField, which reads the database.

See also

Files and folders in the tutorial, Custom fields, and the File type.

Methods

basename

files.basename(object: File) → string

Get the base file name from a path.

dirname

files.dirname(object: File) → string

Get the parent directory path.

exists

files.exists(share?: Share, path?: string = "", user?: User) → bool

Check if a file exists on a share. False only when it is not there; a share that cannot be reached is an error, not a no.

get

files.get(share?: Share, path?: string = "", user?: User, result?: SearchResult) → File

Get a file or directory from a share.

search

files.search(location: mixed, query: mixed, user?: User) → Collection

Search for files matching a query.

splitOnFooter

files.splitOnFooter(file: File, zone: mixed, discard?: bool = false) → array

Split a PDF file on footer zone matches.

splitOnHeader

files.splitOnHeader(file: File, zone: mixed, discard?: bool = false) → array

Split a PDF file on header zone matches.

status

files.status(share?: Share, path?: string = "", user?: User) → string

What a share says about a path, for a script about to act on the answer: “found”, “missing”, “refused” (the account it connects with has no access) or “unreachable” (the storage did not answer). exists() cannot say the last two: on either it records an error and the script runs on, into an else if it has one. Check for “missing” before writing where a file may be.

“missing” means the storage gave no other reason. FTP, SFTP and B2 cannot give one, and a file a person’s own SMB ACL refuses is absent to them.

token

files.token(file: File) → string

Generate a temporary access token URL for a file.