Skip to main content

InstancePathUtils

Utility functions for addressing instances by a dotted path, like "Master.Music", relative to some root instance.

Types​

InstancePath​

</>
type InstancePath = string

A dotted path naming each instance to descend through, like "Master.Music".

InstancePathTable​

</>
type InstancePathTable = {string}

An instance path split into its individual instance names.

Functions​

isInstancePath​

</>
InstancePathUtils.isInstancePath(instancePath: any) → boolean

Checks if the given value is a valid instance path.

toPathTable​

</>
InstancePathUtils.toPathTable(instancePath: InstancePath) → InstancePathTable

Converts an instance path into a table of instance names.

fromPathTable​

</>
InstancePathUtils.fromPathTable(pathTable: InstancePathTable) → InstancePath

Converts a table of instance names into an instance path.

getParentPath​

</>
InstancePathUtils.getParentPath(instancePath: InstancePath) → InstancePath?

Returns the path to the parent of the given path, that is, every name except the last one. Returns nil if the path names a direct child of the root, and so has no parent path. 

InstancePathUtils.getParentPath("Quenty.default") --> "Quenty"
InstancePathUtils.getParentPath("default") --> nil

getName​

</>
InstancePathUtils.getName(instancePath: InstancePath) → string

Returns the name of the instance the path points at, that is, the last name in the path.

InstancePathUtils.getName("Quenty.default") --> "default"

findInstance​

</>
InstancePathUtils.findInstance(
root: Instance,
instancePath: InstancePath,
className: string?
) → Instance?

Finds the instance at the given path underneath the root. Each name in the path must resolve to a child of the given class name, if one is given.

findOrCreateInstance​

</>
InstancePathUtils.findOrCreateInstance(
root: Instance,
instancePath: InstancePath,
className: string,
onCreate: ((instance: Instance) → ())?
) → Instance

Finds the instance at the given path underneath the root, constructing any missing instances along the way. Each newly constructed instance is passed to onCreate before it is parented, if a callback is given.

getPathTo​

</>
InstancePathUtils.getPathTo(
root: Instance,
instance: Instance
) → InstancePath?

Returns the path of the given instance relative to the root, which lets a path be derived from the tree instead of being stored alongside it. Returns nil if the instance is not a descendant of the root.

Note that instance names containing a "." cannot be addressed by a path, so the result will not round-trip through InstancePathUtils.findInstance in that case.

Show raw api
{
    "functions": [
        {
            "name": "isInstancePath",
            "desc": "Checks if the given value is a valid instance path.",
            "params": [
                {
                    "name": "instancePath",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 33,
                "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
            }
        },
        {
            "name": "toPathTable",
            "desc": "Converts an instance path into a table of instance names.",
            "params": [
                {
                    "name": "instancePath",
                    "desc": "",
                    "lua_type": "InstancePath"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "InstancePathTable"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 43,
                "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
            }
        },
        {
            "name": "fromPathTable",
            "desc": "Converts a table of instance names into an instance path.",
            "params": [
                {
                    "name": "pathTable",
                    "desc": "",
                    "lua_type": "InstancePathTable"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "InstancePath"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 55,
                "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
            }
        },
        {
            "name": "getParentPath",
            "desc": "Returns the path to the parent of the given path, that is, every name except the last\none. Returns nil if the path names a direct child of the root, and so has no parent\npath.\n\n```lua\nInstancePathUtils.getParentPath(\"Quenty.default\") --> \"Quenty\"\nInstancePathUtils.getParentPath(\"default\") --> nil\n```",
            "params": [
                {
                    "name": "instancePath",
                    "desc": "",
                    "lua_type": "InstancePath"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "InstancePath?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 74,
                "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
            }
        },
        {
            "name": "getName",
            "desc": "Returns the name of the instance the path points at, that is, the last name in the path.\n\n```lua\nInstancePathUtils.getName(\"Quenty.default\") --> \"default\"\n```",
            "params": [
                {
                    "name": "instancePath",
                    "desc": "",
                    "lua_type": "InstancePath"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 95,
                "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
            }
        },
        {
            "name": "findInstance",
            "desc": "Finds the instance at the given path underneath the root. Each name in the path must\nresolve to a child of the given class name, if one is given.",
            "params": [
                {
                    "name": "root",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "instancePath",
                    "desc": "",
                    "lua_type": "InstancePath"
                },
                {
                    "name": "className",
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 110,
                "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
            }
        },
        {
            "name": "findOrCreateInstance",
            "desc": "Finds the instance at the given path underneath the root, constructing any missing\ninstances along the way. Each newly constructed instance is passed to `onCreate`\nbefore it is parented, if a callback is given.",
            "params": [
                {
                    "name": "root",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "instancePath",
                    "desc": "",
                    "lua_type": "InstancePath"
                },
                {
                    "name": "className",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "onCreate",
                    "desc": "",
                    "lua_type": "((instance: Instance) -> ())?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 138,
                "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
            }
        },
        {
            "name": "getPathTo",
            "desc": "Returns the path of the given instance relative to the root, which lets a path be derived\nfrom the tree instead of being stored alongside it. Returns nil if the instance is not a\ndescendant of the root.\n\nNote that instance names containing a `\".\"` cannot be addressed by a path, so the result\nwill not round-trip through [InstancePathUtils.findInstance] in that case.",
            "params": [
                {
                    "name": "root",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "InstancePath?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 184,
                "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "InstancePath",
            "desc": "A dotted path naming each instance to descend through, like `\"Master.Music\"`.",
            "lua_type": "string",
            "source": {
                "line": 17,
                "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
            }
        },
        {
            "name": "InstancePathTable",
            "desc": "An instance path split into its individual instance names.",
            "lua_type": "{ string }",
            "source": {
                "line": 25,
                "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
            }
        }
    ],
    "name": "InstancePathUtils",
    "desc": "Utility functions for addressing instances by a dotted path, like `\"Master.Music\"`,\nrelative to some root instance.",
    "source": {
        "line": 8,
        "path": "src/instance-path/src/Shared/InstancePathUtils.lua"
    }
}