Files

Scripts can keep plain text files inside the plugin folder.

create file "proplayer300data.txt" at "plugins/HyperScript/"
set file at "plugins/HyperScript/proplayer300data.txt" to "Coins:500"
set {_proplayer300data} to read file at "plugins/HyperScript/proplayer300data.txt"
set {_parts} to split {_proplayer300data} by ":"

CSV files. A .csv file is what a spreadsheet saves: a line for each row, commas between the cells. csv of file at reads one into rows, and the rows are lists inside a list, so every cell is reached with item:

command /prices:
    trigger:
        set {_rows} to csv of file at "plugins/HyperScript/prices.csv" with headers
        for each {_row} in {_rows}:
            send "&e%{_row.item}% &7costs &f%{_row.price}%"
        set {_prices} to column "price" of {_rows}
        send "&7All prices: %{_prices}%"

command /export:
    trigger:
        set {_rows} to [["player", "coins"]]
        for each {_name} in server.players:
            add [{_name}, {%{_name}%.coins}] to {_rows}
        set file at "plugins/HyperScript/coins.csv" to csv of {_rows}
        send "&aWritten."

• A cell that is written as a number is a number, true and false are themselves, an empty cell is not set, and everything else is text. 007 stays text, so that ids keep their zeros.
• With with headers, the names of the columns are taken in lower case: a column Price is {_row.price}.
• A cell with a comma, a quote or a line break in it is written in quotes, as spreadsheets do, and read back the same. Files that use semicolons or tabs between the cells, as spreadsheets write where the comma is the decimal point, are read as well.
• At most 100,000 rows are read from one file.

Paths are written relative to the server folder, with forward slashes, as in "plugins/HyperScript/notes.txt".

command /notes:
    permission: "notes.read"
    trigger:
        set {_folder} to "plugins/HyperScript/notes"
        set {_names} to files in {_folder}
        if size of {_names} == 0:
            send "&7There are no notes."
            stop
        send "&6%size of {_names}% notes:"
        for each {_name} in {_names}:
            set {_path} to "%{_folder}%/%{_name}%"
            set {_lines} to lines of file at {_path}
            set {_when} to last modified of file at {_path}
            set {_day} to {_when} formatted as "d MMM"
            send " &f%{_name}% &8- &7%size of {_lines}% lines, changed %{_day}%"

command /archive <text>:
    permission: "notes.admin"
    trigger:
        set {_from} to "plugins/HyperScript/notes/%arg.1%.txt"
        if not file at {_from} exists:
            send "&cThere is no note called %arg.1%."
            stop
        move file at {_from} to "plugins/HyperScript/archive/%arg.1%.txt"
        send "&aArchived."

command /backupnotes:
    permission: "notes.admin"
    trigger:
        set {_notes} to "plugins/HyperScript/notes"
        set {_backup} to "plugins/HyperScript/notes-backup"
        if folder at {_backup} exists:
            delete folder at {_backup} with its files
        create folder {_backup}
        set {_bytes} to 0
        for each {_path} in all files in {_notes}:
            copy file at "%{_notes}%/%{_path}%" to "%{_backup}%/%{_path}%"
            add size of file at "%{_notes}%/%{_path}%" to {_bytes}
        set {_groups} to folders in {_notes}
        send "&aCopied %{_bytes}% bytes from %size of {_groups}% folders of notes."

on load:
    # An empty folder left over from last time goes; one with something in it is left alone.
    if size of (files in "plugins/HyperScript/temp") == 0:
        delete folder at "plugins/HyperScript/temp"

• A folder that is not there has no files in it: files in gives an empty list, not a mistake.
• files in and folders in may be asked of "plugins/HyperScript" itself; HyperScript's own files and folders are left out of the answer. A listing has at most 1000 names.
• move file and copy file make the folders the new place needs.

Scripts that look after scripts. The scripts folder is closed to the statements above, so that a path made from what a player typed can never reach it. A script that sets a server up can still see which scripts there are, take one out, and read and change another's options:

command /cleanup:
    permission: "hyperscript.admin"
    trigger:
        for each {_script} in all scripts:
            if {_script} is not this script:
                delete script {_script}
        send "&aEvery other script was taken out."

command /servername <text>:
    permission: "hyperscript.admin"
    trigger:
        if not script "Sidebar" exists:
            send "&cThere is no Sidebar.hs here."
            stop
        set {_old} to option "name" of script "Sidebar"
        set option "name" of script "Sidebar" to arg.1
        send "&aThe sidebar was called %{_old}% and is now called %arg.1%."

• With hot reloading on, a script that was changed or taken out is loaded again by itself; otherwise run /hyperscript reload, which a script can do with execute console command "hyperscript reload".
• An option a script does not have is not added: set option stops the trigger and says so. Ask first with option ... of script ... is set.
• These follow files.enabled like everything else here.

• Scripts can only reach files inside plugins/HyperScript/. A path that leads anywhere else, including through .. or an absolute path, stops the trigger with a warning in the console.
• Inside that folder, HyperScript's own files are off limits: config.yml, data.json, the database, and the scripts and backups folders.
• These limits exist because paths are often built from what players type. Even so, prefer names you control, such as %player.uuid%, over raw player input in a path.
• Files are read as UTF-8 text. read file refuses files larger than 1 MB.
• File access happens immediately, on the thread the script is running on. That is fine for small files; put work on large ones inside async:.
• For data that belongs to a player or to the server as a whole, variables are usually the better tool: they are saved, backed up and cached for you. Files are for things other programs read or write, such as logs and exports.
• files.enabled: false in config.yml turns all of this off.