{
    "$meta": {
        "description": "A `file` object can be acquired by either using [File](#COMPUTER_FILE) or [overflow](#METALIB_OVERFLOW). The `classID` used for this object is `\"file\"`."
    },
    "chmod": {
        "description": "Modifies the `file` permissions. Optionally, these permissions can also be applied recursively. The format for applying permissions is as follows: `\"[references][operator][modes]\"`. The references type is defined through three possible types: user `\"u\"`, group `\"g\"`, and other `\"o\"`. The operator is used to define if permissions get added `\"+\"` or removed `\"-\"`. There are three different modes that can be modified: read `\"r\"`, write `\"w\"`, and execute `\"x\"`. So, for example, `\"o-wrx\"` would remove all possible permissions for others. To add all permissions for others again, `\"o+wrx\"` would be used. In case the modification fails, this method will return a `string` containing information about the reason. Otherwise, an empty `string` is returned. In case any type other than `number` is used for the `isRecursive` parameter, an error will be thrown preventing further script execution.",
        "example": [
            "hostComputer = get_shell(\"root\", \"test\").host_computer",
            "rootFolder = hostComputer.File(\"/bin\")",
            "oldPermissions = rootFolder.permissions",
            "rootFolder.chmod(\"o-wrx\", true)",
            "newPermissions = rootFolder.permissions",
            "print(\"Old permissions: \" + oldPermissions)",
            "print(\"New permissions: \" + newPermissions)"
        ]
    },
    "copy": {
        "description": "Copies the `file` to the provided path. Files can only be copied if the user has read and write permissions or is root. The new filename has to be below 128 characters and alphanumeric. After success, this method will return a `number` with the value one. Otherwise, it will return a `string` containing information about the reason for failure. If any of the parameter types deviate from the method signature, this method is used within an SSH encryption process, the new name exceeds 128 characters, or the path is too long, an error will be thrown, causing an interruption of script execution. In case the current file gets deleted, this method will return `null`.",
        "example": [
            "hostComputer = get_shell(\"root\", \"test\").host_computer",
            "passwdFile = hostComputer.File(\"/etc/passwd\")",
            "copyResult = passwdFile.copy(\"/etc/\", \"duplicate\")",
            "if typeof(copyResult) == \"string\" then",
            "   print(\"There was an error while copying file: \" + copyResult)",
            "else",
            "   print(\"File got copied successfully.\")",
            "end if"
        ]
    },
    "move": {
        "description": "Moves the `file` to the provided path. Files can only be moved if the user has read and write permissions or is root. The new filename has to be below 128 characters and alphanumeric. After success, this method will return a `number` with the value one. Otherwise, this method will return a `string` with details. If any of the parameter types deviate from the method signature, this method is used within an SSH encryption process, the new name exceeds 128 characters, or the path is too long, an error will be thrown, causing an interruption of script execution. In case the current file gets deleted, this method will return `null`.",
        "example": [
            "hostComputer = get_shell(\"root\", \"test\").host_computer",
            "passwdFile = hostComputer.File(\"/etc/passwd\")",
            "moveResult = passwdFile.move(\"/root/\", \"newFileName\")",
            "if typeof(moveResult) == \"string\" then",
            "   print(\"There was an error while moving file: \" + moveResult)",
            "else",
            "   print(\"File got moved successfully.\")",
            "end if"
        ]
    },
    "symlink": {
        "description": "Creates a symlink to the specified path. Symlinks can only be created if the user has write permissions or is root. The new filename must be alphanumeric and under 128 characters. Upon success, this method returns a `number` with the value one. On failure, it returns a `string` with details. If any parameters deviate from the method signature, if used within an SSH encryption process, if the new name exceeds 128 characters, or if the path is too long, an error will be thrown, interrupting script execution. If the current file is deleted, this method will return `null`.",
        "example": [
            "hostComputer = get_shell(\"root\", \"test\").host_computer",
            "lsFile = hostComputer.File(\"/bin/ls\")",
            "symResult = lsFile.symlink(\"/bin\", \"alternativeLS\")",
            "if typeof(symResult) == \"string\" then",
            "   print(\"There was an error while creating symlink: \" + symResult)",
            "else",
            "   print(\"Symlink got created successfully.\")",
            "end if"
        ]
    },
    "rename": {
        "description": "Rename the file with the name provided. Files can only be renamed if the user has write permissions or is root. The new filename has to be below 128 characters and alphanumeric. On failure, this method will return a `string` with details. Otherwise, this method will return an empty string. If this method is used within an SSH encryption process, an error will be thrown, causing the script execution to be interrupted. In case the provided name is `null`, this method will return a `number` with the value zero.",
        "example": [
            "hostComputer = get_shell(\"root\", \"test\").host_computer",
            "passwdFile = hostComputer.File(\"/etc/passwd\")",
            "renameResult = passwdFile.rename(\"renamed\")",
            "if typeof(renameResult) == \"string\" then",
            "   print(\"There was an error while renaming file: \" + renameResult)",
            "else",
            "   print(\"File got renamed successfully.\")",
            "end if"
        ]
    },
    "path": {
        "description": "Returns a `string` containing the file path. If the file is a symlink, the optional `symlinkOrigPath` argument can be set to return the original path of the linked file instead. If the file has been deleted, this method will still return the path it had prior to deletion.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "passwdFile = hostComputer.File(\"/etc/passwd\")",
            "print(\"File location: \" + passwdFile.path)"
        ]
    },
    "is_folder": {
        "description": "Returns a `number`. The value is one if the file is a folder, zero otherwise. In case the file gets deleted this method will return `null` instead.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "etcFolder = hostComputer.File(\"/etc\")",
            "print(\"Is a folder: \" + etcFolder.is_folder)"
        ]
    },
    "parent": {
        "description": "Returns the parent folder of the current file or folder. In case there is no parent folder `null` will be returned instead. In case the file gets deleted this method will return `null` as well.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "etcFolder = hostComputer.File(\"/etc\")",
            "print(\"Parent path: \" + etcFolder.parent.path)"
        ]
    },
    "name": {
        "description": "Returns a `string` with the name of the file. In case the file gets deleted this method will return `null` instead.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "passwdFile = hostComputer.File(\"/etc/passwd\")",
            "print(\"Filename: \" + passwdFile.name)"
        ]
    },
    "allow_import": {
        "description": "Returns a `number`. If the file is binary and can be imported by other scripts, the value will be one; otherwise, the value will be zero. In case the file gets deleted, this method will cause a crash.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "lsBinary = hostComputer.File(\"/bin/ls\")",
            "print(\"File can be imported: \" + lsBinary.allow_import)"
        ]
    },
    "get_content": {
        "description": "Returns a `string` representing the content of the file. To read a file, the user requires read access or being root. Note that you cannot read a binary file. In case of failure, `null` will be returned. If this method is used within an SSH encryption process, an error will be thrown, preventing any further script execution.",
        "example": [
            "hostComputer = get_shell(\"root\", \"test\").host_computer",
            "passwdFile = hostComputer.File(\"/etc/passwd\")",
            "print(\"File content: \" + passwdFile.get_content)"
        ]
    },
    "set_content": {
        "description": "Saves text into a `file`. The content will not get appended to the `file`; therefore, existing content will be overridden. To set new content, the user requires write permissions or being root. Keep in mind that text files cannot exceed the character limit of 160,000. In case setting the content was successful, a `number` with the value one will be returned. Otherwise, a `string` with details will be returned. If this method is used within an SSH encryption process, an error will be thrown, preventing any further script execution. If the provided content is `null` or permissions are lacking, this method will return a `number` with the value zero. In case the file gets deleted this method will return `null`.",
        "example": [
            "hostComputer = get_shell(\"root\", \"test\").host_computer",
            "passwdFile = hostComputer.File(\"/etc/passwd\")",
            "setResult = passwdFile.set_content(\"moo\")",
            "if typeof(setResult) == \"string\" then",
            "   print(\"There was an error while setting file content: \" + setResult)",
            "else if setResult == 0 then",
            "   print(\"Unable to set content of file!\")",
            "else",
            "   print(\"File content got changed successfully.\")",
            "end if"
        ]
    },
    "is_binary": {
        "description": "Returns a `number`. If the file is a binary, the value will be one; otherwise, it will be zero. In case the file gets deleted, this method will return `null` instead.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "lsBinary = hostComputer.File(\"/bin/ls\")",
            "print(\"File is a binary: \" + lsBinary.is_binary)"
        ]
    },
    "is_symlink": {
        "description": "Returns a `number`. If the file is a symlink, the value will be one; otherwise, it will be zero. In case the file gets deleted, this method will return `null` instead.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "lsBinary = hostComputer.File(\"/bin/ls\")",
            "print(\"File is a symlink: \" + lsBinary.is_symlink)"
        ]
    },
    "has_permission": {
        "description": "Returns a `number` indicating if the user who launched the script has the requested permissions. One will indicate that the user has the correct permissions. In case permissions are lacking, the value will be zero. There are three different permission types: read `\"r\"`, write `\"w\"`, and execute `\"x\"`. In case the file gets deleted, this method will return `null` instead.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "lsBinary = hostComputer.File(\"/bin/ls\")",
            "print(\"Is able to execute ls: \" + lsBinary.has_permission(\"x\"))"
        ]
    },
    "delete": {
        "description": "Delete the current file. To delete files, write permissions are required or being root. In case of failure, a `string` with details will be returned. Otherwise, an empty `string` gets returned. Please note that deleting a file will leave a log entry.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "lsBinary = hostComputer.File(\"/bin/ls\")",
            "deletionResult = lsBinary.delete",
            "if typeof(deletionResult) == \"string\" and deletionResult.len > 0 then",
            "   print(\"There was an error while deleting a file: \" + deletionResult)",
            "else",
            "   print(\"File got deleted successfully.\")",
            "end if"
        ]
    },
    "get_folders": {
        "description": "Returns a `list` of folders. In case the current entity is a file instead of a folder this method will return `null`, so it is advisable to first use the `is_folder` function before calling this method. In case the current folder gets deleted this method will return `null` as well.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "binFolder = hostComputer.File(\"/home\")",
            "folders = binFolder.get_folders",
            "for folder in folders",
            "   print(folder.path)",
            "end for"
        ]
    },
    "get_files": {
        "description": "Returns a `list` of files. In case the current entity is a file instead of a folder this method will return `null`, so it is advisable to first use the `is_folder` function before calling this method. In case the current folder gets deleted this method will return `null` as well.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "binFolder = hostComputer.File(\"/bin\")",
            "files = binFolder.get_files",
            "for file in files",
            "   print(file.path)",
            "end for"
        ]
    },
    "permissions": {
        "description": "Returns a `string` with the current file permissions. In case the current file gets deleted, this method will return `null`. The format for this permissions `string` is as follows: `\"[fileType][wrx](u)[wrx](g)[wrx](o)\"`. The file type is either `\"d\"` in case it's a directory or `\"-\"`. The user type gets defined through three possible types: user `\"u\"`, group `\"g\"`, and other `\"o\"`. There are three different permission types: read `\"r\"`, write `\"w\"`, and execute `\"x\"`. An example of a `string` returned by this method would be `\"-rwxr-xr-x\"`. Taking the latter as an example, the following things become clear:\n* The provided file is not a directory.\n* The user has full access.\n* The group and others have almost all permissions besides writing.\n",
        "example": [
            "hostComputer = get_shell.host_computer",
            "binFolder = hostComputer.File(\"/bin\")",
            "permissions = binFolder.permissions",
            "fileType = permissions[0]",
            "permissionsForUser = permissions[1:4]",
            "permissionsForGroup = permissions[4:7]",
            "permissionsForOther = permissions[7:10]",
            "print(\"File type: \" + fileType)",
            "print(\"User permissions: \" + permissionsForUser)",
            "print(\"Group permissions: \" + permissionsForGroup)",
            "print(\"Other permissions: \" + permissionsForOther)"
        ]
    },
    "owner": {
        "description": "Returns a `string` with the name of the file owner. User permissions get applied to whoever is the owner of a file. In case the current file gets deleted, this method will return `null`.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "lsBinary = hostComputer.File(\"/bin/ls\")",
            "print(\"Owner of ls is: \" + lsBinary.owner)"
        ]
    },
    "set_owner": {
        "description": "Change the owner of this file. Optionally the owner can get applied recursively. The owner's name cannot exceed 15 characters. Additionally either write permissions or being root is required. In case of failure a `string` gets returned containing the cause. Otherwise an empty `string` gets returned. In case the current file gets deleted or the passed owner value is not a `string`, this method will return `null`. If the passed owner value is empty, the owner value is longer than 15 characters, or the passed recursive value deviates from its original type, an error will be thrown, interrupting further script execution.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "lsBinary = hostComputer.File(\"/bin/ls\")",
            "ownerResult = lsBinary.set_owner(\"root\")",
            "if typeof(ownerResult) == \"string\" then",
            "   print(\"There was an error while changing owner: \" + ownerResult)",
            "else",
            "   print(\"File owner changed successfully.\")",
            "end if"
        ]
    },
    "group": {
        "description": "Returns a `string` with the name of the group to which this file belongs. Group permissions get applied to whoever is the owner of a file. In case the current file gets deleted, this method will return `null`.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "lsBinary = hostComputer.File(\"/bin/ls\")",
            "print(\"File is related to following group: \" + lsBinary.group)"
        ]
    },
    "set_group": {
        "description": "Change the group related to this file. Optionally the group can get applied recursively. The group name cannot exceed 15 characters. Additionally either write permissions or being root is required. In case of failure, a `string` with details. On success, an empty `string` gets returned. In case the current file gets deleted or the passed group is not a `string`, this method will return `null`. If the passed group value is empty, the group value is longer than 15 characters, or the passed recursive value deviates from its original type, an error will be thrown, preventing further script execution.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "lsBinary = hostComputer.File(\"/bin/ls\")",
            "ownerResult = lsBinary.set_group(\"root\")",
            "if typeof(ownerResult) == \"string\" then",
            "   print(\"There was an error while changing group: \" + ownerResult)",
            "else",
            "   print(\"File group changed successfully.\")",
            "end if"
        ]
    },
    "size": {
        "description": "Returns a `string` with the size of the file in bytes. There is no correlation between file size and actual file content. Instead, the file size is depending on the name of the file. In case the current file gets deleted, this method will return `null`.",
        "example": [
            "hostComputer = get_shell.host_computer",
            "lsBinary = hostComputer.File(\"/bin/ls\")",
            "size = lsBinary.size",
            "if size.to_int > 1000 then",
            "   print(\"File size is bigger than 1000 bytes.\")",
            "else",
            "   print(\"File size is below 1000 bytes.\")",
            "end if"
        ]
    }
}