Objects and member access

Most of what a script does beyond arithmetic and text is done through objects: dates, collections, files, shares, web requests, spreadsheets. An object has properties you can read and methods you can call. This page gives the rules that every object follows. What each object offers is in the library reference.

The mash object

Every script has one object that it did not create: mash. Everything else hangs off it. mash.files works with files, mash.date(...) makes a date, mash.collect(...) makes a collection.

There is also event, which holds what started the script, such as the file that was uploaded. In a plain run with no trigger, event is empty. Like mash, event cannot be assigned to.

Natural

set today to mash.date("2026-03-15")
set list to mash.collect([3, 1, 2])
printline today.format("D j M Y")
printline list.count()

Sun 15 Mar 2026
3

Standard

today = mash.date("2026-03-15")
list = mash.collect([3, 1, 2])
printline(today.format("D j M Y"))
printline(list.count())

Sun 15 Mar 2026
3

Reading a property

object.name reads a property. object["name"] reads the same thing. After a dot, every word is a name, even a reserved word.

Natural

set d to mash.date("2026-03-15")
printline d.year
printline d["month"]

2026
3

Standard

d = mash.date("2026-03-15")
printline(d.year)
printline(d["month"])

2026
3

Calling a method

object.name(arguments) calls a method. The ( must come straight after the name. Methods that return an object can be chained:

Natural

set d to mash.date("2026-01-02")
printline d.copy().addDays(1).addMonths(1).format("Y-m-d")

2026-02-03

Standard

d = mash.date("2026-01-02")
printline(d.copy().addDays(1).addMonths(1).format("Y-m-d"))

2026-02-03

A method call needs its brackets, even with no arguments.

Writing a property

object.name = value and object["name"] = value set a property, for the objects that allow it. An object that does not allow it refuses the write, and the error is recorded like any other. A script cannot change a database record’s own fields by writing to them; it goes through the methods that the object offers.

Objects are shared

Two variables can name one object. Changing it through one name changes it through the other. This is different from arrays and dictionaries, which are copied. See Values and types.

Some objects change in place when you call a method on them. Dates do: d.addDays(5) moves d itself, and gives it back. Take a copy with .copy() first when the original must stay.

Natural

set start to mash.date("2026-03-15")
set moved to start.addDays(5)
printline start.format("Y-m-d")
printline moved.format("Y-m-d")

2026-03-20
2026-03-20

Standard

start = mash.date("2026-03-15")
moved = start.addDays(5)
printline(start.format("Y-m-d"))
printline(moved.format("Y-m-d"))

2026-03-20
2026-03-20

Collections

mash.collect(array) wraps an array or a dictionary in a collection, which has methods that a plain array lacks.

Method	Gives
count()	the number of items
first(), last()	the first or last item
map(block)	a collection of each item passed through the block
filter(block)	a collection of the items for which the block is true
sort()	a collection in order
sum()	the total
has(key), keys()	whether a key exists, and the list of keys
values()	the items, numbered from 0 again
toArray()	a plain array

Natural

set list to mash.collect([3, 1, 2])
printline list.sum()
printline list.map(block n { return n * 10 }).toArray()
printline list.filter(block n { return n is more than 1 }).values().toArray()

6
Array [
    30,
    10,
    20
]
Array [
    3,
    2
]

Standard

list = mash.collect([3, 1, 2])
printline(list.sum())
printline(list.map(block(n) { return n * 10 }).toArray())
printline(list.filter(block(n) { return n > 1 }).values().toArray())

6
Array [
    30,
    10,
    20
]
Array [
    3,
    2
]

A method that takes a callback, such as map, takes a block, as an anonymous block or the bare name of a block with parameters. It never takes a text name or a PHP function name.

Natural

set f to mash.collect(["a"]).map("strtoupper")
printline mash.error.message

"map" runs the argument it is given, so it takes a block and nothing else. The first argument was the PHP function "strtoupper". Write map(block item { ... }) instead.

Standard

f = mash.collect(["a"]).map("strtoupper")
printline(mash.error.message)

"map" runs the argument it is given, so it takes a block and nothing else. The first argument was the PHP function "strtoupper". Write map(block item { ... }) instead.

Caution

filter and sort keep each item’s original position as its key. A filtered or sorted collection printed or looped over by key shows gaps and old numbers: sorting [3, 1, 2] gives the keys 1, 2, 0. Call .values() to number the result from 0 again before you turn it into an array.

Asking an object what it offers

The built-in explain prints the properties and methods of an object, with their arguments, as the script itself would see them:

explain mash.math

It lists only what a script can use. What it leaves out, a script cannot reach.

What a script cannot reach

A script runs inside limits that you cannot lift from the script. These rules apply to every object, and they are the same on Foldr Cloud and on an appliance.

Names that start with an underscore

A method whose name starts with _ is internal. A script cannot call it.

Natural

mash._releaseLocks()
printline mash.error.message

"_releaseLocks" is not accessible.

Standard

mash._releaseLocks()
printline(mash.error.message)

"_releaseLocks" is not accessible.

Hidden members

An object can hide a method or property from scripts. A hidden member behaves as not accessible. It does not appear in explain. You do not need to know what is hidden; if the library reference does not list a member, a script cannot use it.

Natural

mash.error.setExceptionHandler(1)
printline mash.error.message

"setExceptionHandler" is not accessible.

Standard

mash.error.setExceptionHandler(1)
printline(mash.error.message)

"setExceptionHandler" is not accessible.

Members that do not exist

What happens depends on where the member is missing:

You write	Result
mash.nosuchobject	the script stops: mash.nosuchobject does not exist. (with Did you mean mash.users? when a close name exists)
mash.nosuchmethod()	the script stops: Method mash.nosuchmethod does not exist
collection.nosuch	an error is recorded, and the statement fails: Item "nosuch" does not exist in collection.
collection.nosuch()	an error is recorded, and the statement fails: Method Collection::nosuch does not exist.
"text".anything()	an error is recorded: Unable to call method "anything" of non-object "string".

The first two stop on purpose, so that a misspelt object name does not quietly do nothing.

Callbacks must be blocks

Anything that runs a callback takes a block. A text name, a PHP function name or a block’s own methods are all refused. A block has no methods of its own.

Identifiers

Treat an id as text. On Foldr Cloud the id of a share, user, group or similar is a UUID such as 0191..., and on an appliance it can be a number. A script that converts an id to a number works on one and breaks on the other. Pass the id on as it is.

Permissions

Objects apply the permissions of the user the script runs as. Reading a share that user cannot see does not return it, and writing where that user cannot write fails.

Availability

Some objects exist only on an appliance, or only with a licence or a feature switched on. The library reference marks each of these on its page. On Foldr Cloud, objects that reach the network refuse addresses that are inside Foldr’s own network.