File.enso

import project.Any.Any
import project.Data.Array.Array
import project.Data.Json.JS_Object
import project.Data.Numbers.Integer
import project.Data.Text.Encoding.Encoding
import project.Data.Text.Extensions
import project.Data.Text.Matching_Mode.Matching_Mode
import project.Data.Text.Text
import project.Data.Time.Date_Time.Date_Time
import project.Data.Vector.Vector
import project.Enso_Cloud.Data_Link.Data_Link
import project.Enso_Cloud.Data_Link_Helpers
import project.Enso_Cloud.Enso_File.Enso_File
import project.Error.Error
import project.Errors.Common.Dry_Run_Operation
import project.Errors.Common.Type_Error
import project.Errors.File_Error.File_Error
import project.Errors.Illegal_Argument.Illegal_Argument
import project.Errors.Problem_Behavior.Problem_Behavior
import project.Function.Function
import project.Meta
import project.Metadata.Display
import project.Metadata.Widget
import project.Nothing.Nothing
import project.Panic.Panic
import project.Runtime.Context
import project.Runtime.Managed_Resource.Managed_Resource
import project.System.File.Data_Link_Access.Data_Link_Access
import project.System.File.File_Access.File_Access
import project.System.File.File_Permissions.File_Permissions
import project.System.File.Generic.File_Like.File_Like
import project.System.File.Generic.File_Write_Strategy.File_Write_Strategy
import project.System.File.Generic.Writable_File.Writable_File
import project.System.File.Local_File_Write_Strategy
import project.System.Input_Stream.Input_Stream
import project.System.Output_Stream.Output_Stream
import project.Warning.Warning
from project.Data.Boolean import Boolean, False, True
from project.Metadata.Choice import Option
from project.System.File_Format import Auto_Detect, File_Format

polyglot java import java.io.File as Java_File
polyglot java import java.io.InputStream as Java_Input_Stream
polyglot java import java.io.OutputStream as Java_Output_Stream
polyglot java import java.nio.file.StandardCopyOption
polyglot java import java.nio.file.StandardOpenOption
polyglot java import java.time.ZonedDateTime
polyglot java import org.enso.base.DryRunFileManager
polyglot java import org.enso.base.file_system.File_Utils

## Represents a file or folder on the filesystem.
@Builtin_Type
type File
    ## ALIAS new file
       GROUP Input
       ICON data_input

       Creates a new file object, pointing to the given path.

       Relative paths are resolved relative to the directory containing the
       currently running workflow. Thus, if the workflow is running in the Cloud,
       the relative paths will be resolved to Cloud files.

       Arguments:
       - path: The path to the file that you want to create, or a file itself. The
         latter is a no-op.

       > Example
         Create a new file pointing to the `data.csv` file in the project directory.

             import Standard.Base.System.File.File
             import Standard.Examples

             example_new = File.new Examples.csv_path
    new : (Text | File) -> Any ! Illegal_Argument
    new path = case path of
        _ : Text -> if path.contains "://" . not then resolve_path path else
            protocol = path.split "://" . first
            file_system = File_System_SPI.get_type protocol False
            if file_system.is_nothing then Error.throw (Illegal_Argument.Error "Unsupported protocol "+protocol) else
                file_system.new path
        _ : File -> path
        _ ->
            ## Check to see if a valid "File" type.
            if ((File_System_SPI.get_types False).any file_type-> path.is_a file_type) then path else
                Error.throw (Illegal_Argument.Error "The provided path is neither a Text, nor any recognized File-like type.")


    ## ICON folder_add
       Creates a temporary file which will be deleted when Enso exits.
    create_temporary_file : Text -> Text -> File
    create_temporary_file prefix="temp" suffix=".tmp" =
        java_file = Java_File.createTempFile prefix suffix
        java_file.deleteOnExit
        File.new java_file.getAbsolutePath

    ## PRIVATE
       Create a dry run temporary file which will be deleted when Enso exits.

       The same temporary file is returned for paths that point to the same
       location (not accounting for symlinks).

       If this file is a temporary file that was generated by
       `create_dry_run_file` on another file, it is returned as-is.

       Arguments:
       - copy_original: If `True`, the created dry run file is 'synchronized'
         with the original file - the file is copied to the temporary file, or
         if the original file does not exist - it is ensured that the temporary
         file also does not exist. If `False`, no actions are taken.
    create_dry_run_file : Boolean -> File ! File_Error
    create_dry_run_file self copy_original=False =
        temp_path = DryRunFileManager.getTemporaryFile self.absolute.normalize.path
        if temp_path.is_nothing then Error.throw (File_Error.IO_Error "Unable to create a temporary file.") else
            temp = File.new temp_path
            if copy_original then Context.Output.with_enabled <| Panic.rethrow <|
                case self.exists of
                    True ->
                        self.copy_to temp replace_existing=True
                    False ->
                        temp.delete_if_exists

            ## Attach a warning to the file that it is a dry run
            warning = Dry_Run_Operation.Warning "Only a dry run has occurred, with data written to a temporary file.  Press the Write button ▶ to write the actual file."
            Warning.attach warning temp

    ## ALIAS current directory
       ICON metadata

       Returns the current working directory (CWD) of the current program.

       > Example
         Get the program's current working directory.

             import Standard.Base.System.File.File

             example_cwd = File.current_directory
    current_directory : File
    current_directory = get_cwd

    ## ALIAS home directory
       ICON folder

       Returns the home directory of the current user.

       > Example
         Get the current user's home directory.

             import Standard.Base.System.File.File

             example_home = File.home
    home : File
    home = @Builtin_Method "File.home"

    ## PRIVATE
       ADVANCED
       Creates a new output stream for this file and runs the specified action
       on it.

       The created stream is automatically closed when `action` returns (even
       if it returns exceptionally).

       Arguments:
       - open_options: A vector of `File_Access` objects determining how to open
         the stream. These options set the access properties of the stream.
       - action: A function that operates on the output stream and returns some
         value. The value is returned from this method.

       > Example
         Perform an action on an output stream with the file open for writing.

             import Standard.Base.System.File.File_Access.File_Access
             import Standard.Examples

             example_with_stream =
                 file = Examples.scratch_file
                 action = stream -> stream.write_bytes "hello".utf_8
                 file.with_output_stream [File_Access.Create, File_Access.Write] action
    with_output_stream : Vector File_Access -> (Output_Stream -> Any ! File_Error) -> Any ! File_Error
    with_output_stream self (open_options : Vector) action =
        new_output_stream : File -> Vector File_Access -> Output_Stream ! File_Error
        new_output_stream file open_options =
            opts = open_options . map (_.to_java)
            stream = File_Error.handle_java_exceptions file (file.output_stream_builtin opts)

            ## Re-wrap the File Not Found error to return the parent directory
               instead of the file itself, as that is the issue if not present.
            wrapped = stream.catch File_Error error-> case error of
                File_Error.Not_Found file_path -> Error.throw (File_Error.Not_Found file_path.parent)
                _ -> stream
            Output_Stream.new wrapped (File_Error.handle_java_exceptions self)

        Context.Output.if_enabled disabled_message="As writing is disabled, cannot write to a file. Press the Write button ▶ to perform the operation." panic=False <|
            open_as_data_link = (open_options.contains Data_Link_Access.No_Follow . not) && (Data_Link.is_data_link self)
            if open_as_data_link then Data_Link_Helpers.write_data_link_as_stream self open_options action else
                # We ignore the Data_Link_Access options at this stage:
                just_file_options = open_options.filter opt-> opt.is_a File_Access
                Managed_Resource.bracket (new_output_stream self just_file_options) (_.close) action

    ## PRIVATE
       Creates a new output stream for this file. Recommended to use
       `File.with_output_stream` instead, which does resource management.

       Arguments:
       - options: A vector of `File_Access` objects determining how to open
         the stream. These options set the access properties of the stream.
    output_stream_builtin : Vector File_Access -> Java_Output_Stream
    output_stream_builtin self options = @Builtin_Method "File.output_stream_builtin"

    ## PRIVATE
       Creates a new input stream for this file. Recommended to use
       `File.with_input_stream` instead, which does resource management.

       Arguments:
       - open_options: A vector of `StandardOpenOption` polyglot objects
         determining how to open the stream. These options set the access
         properties of the stream.
    input_stream_builtin : Vector StandardOpenOption -> Java_Input_Stream
    input_stream_builtin self options = @Builtin_Method "File.input_stream_builtin"

    ## PRIVATE
       ADVANCED
       Creates a new input stream for this file and runs the specified action
       on it.

       Arguments:
       - open_options: A vector of `File_Access` objects determining how to open
         the stream. These options set the access properties of the stream.
       - action: A function that operates on the input stream and returns some
         value. The value is returned from this method.

       The created stream is automatically closed when `action` returns (even
       if it returns exceptionally).

       > Example
         Perform an action on an input stream with the file open for reading.

             import Standard.Base.System.File.File_Access.File_Access
             import Standard.Examples

             example_with_stream =
                 file = Examples.csv
                 action = stream -> stream.read_all_bytes
                 file.with_input_stream [File_Access.Create, File_Access.Read] action
    with_input_stream : Vector File_Access -> (Input_Stream -> Any ! File_Error) -> Any ! File_Error
    with_input_stream self (open_options : Vector) action =
        new_input_stream : File -> Vector File_Access -> Input_Stream ! File_Error
        new_input_stream file open_options =
            opts = open_options . map (_.to_java)
            stream = File_Error.handle_java_exceptions file (file.input_stream_builtin opts)
            Input_Stream.new stream (File_Error.handle_java_exceptions self) associated_source=self

        if self.is_directory then Error.throw (File_Error.IO_Error self "File '"+self.path+"' is a directory") else
            open_as_data_link = (open_options.contains Data_Link_Access.No_Follow . not) && (Data_Link.is_data_link self)
            if open_as_data_link then Data_Link_Helpers.read_data_link_as_stream self open_options action else
                # We ignore the Data_Link_Access options at this stage:
                just_file_options = open_options.filter opt-> opt.is_a File_Access
                Managed_Resource.bracket (new_input_stream self just_file_options) (_.close) action

    ## ALIAS load, open, import
       GROUP Input
       ICON data_input
       Read a file using the specified file format

       Arguments:
       - format: A `File_Format` object used to read file into memory.
         If `Auto_Detect` is specified; the provided file determines the specific
         type and configures it appropriately. If there is no matching type then
         a `File_Error.Unsupported_Type` error is returned.
       - on_problems: Specifies the behavior when a problem occurs during the
         function.
         By default, a warning is issued, but the operation proceeds.
         If set to `Report_Error`, the operation fails with a dataflow error.
         If set to `Ignore`, the operation proceeds without errors or warnings.

       > Example
         Read the first sheet of an XLSX from disk and convert it into a table.

             from Standard.Table import all
             import Standard.Examples

             example_xlsx_to_table = Examples.xlsx.read

       > Example
         Read the sheet named `Dates` from an XLS and convert it to a table.

             from Standard.Table import all
             import Standard.Examples

             example_xls_to_table = Examples.xls.read (..Sheet 'Dates')
    @format File_Format.default_widget
    read : File_Format -> Problem_Behavior -> Any ! File_Error
    read self format=Auto_Detect (on_problems : Problem_Behavior = ..Report_Warning) =
        if self.exists.not then Error.throw (File_Error.Not_Found self) else
            if self.is_directory then Error.throw (Illegal_Argument.Error "Cannot `read` a directory, use `list`.") else
                if Data_Link.is_data_link self then Data_Link_Helpers.read_data_link self format on_problems else
                    resolved_format = File_Format.resolve format
                    resolved_format.read self on_problems

    ## ALIAS load bytes, open bytes
       ICON data_input
       Reads all bytes in this file into a byte vector.

       > Example
         Read all of the bytes in the file.

             import Standard.Examples

             example_read_bytes = Examples.csv.read_bytes
    read_bytes : Vector ! File_Error
    read_bytes self =
        opts = [File_Access.Read]
        self.with_input_stream opts (_.read_all_bytes)

    ## ALIAS load text, open text
       ICON data_input
       Reads the whole file into a `Text`, with specified encoding.

       Arguments:
       - encoding: The text encoding to decode the file with. Defaults to UTF-8.
       - on_problems: Specifies the behavior when a problem occurs during the
         function.
         By default, a warning is issued, but the operation proceeds.
         If set to `Report_Error`, the operation fails with a dataflow error.
         If set to `Ignore`, the operation proceeds without errors or warnings.

       > Example
         Read the contents of the file.

             import Standard.Examples

             example_read = Examples.csv.read
    @encoding Encoding.default_widget
    read_text : Encoding -> Problem_Behavior -> Text ! File_Error
    read_text self (encoding : Encoding = Encoding.default) (on_problems : Problem_Behavior = ..Report_Warning) =
        bytes = self.read_bytes
        Text.from_bytes bytes encoding on_problems

    ## GROUP Operators
       ICON folder
       Join two path segments together.

       Arguments:
       - subpath: The path to join to the path of `self`.

       > Example
         Concatenate two file path segments.

             import Standard.Examples

             example_append = Examples.data_dir / "scratch_file"
    @subpath get_child_widget
    / : Text -> File
    / self (subpath : Text) = self.resolve subpath

    ## GROUP Calculations
       ICON folder
       Join two or more path segments together, normalizing the `..` and `.` subpaths.

       Arguments:
       - subpaths: The path segment or segments to join to the path of `self`.

       > Example
         Concatenate two file path segments.

             import Standard.Examples

             example_append = Examples.data_dir.join "scratch_file"

       > Example
         Concatenate multiple file path segments and normalizes the result.

             import Standard.Examples

             example_append = Examples.data_dir.join ["2022", "10", "31", "scratch_file"]
    @subpaths get_child_widget
    join : (Text | File | Vector) -> File
    join self subpaths = case subpaths of
        _ : Vector -> (subpaths.fold self c->p-> c / p) . normalize
        _ -> self.join [subpaths]

    ## PRIVATE
       Internal method to join two path segments together.
    resolve : Text -> File
    resolve self (subpath : Text) = @Builtin_Method "File.resolve"

    ## PRIVATE
       Convert the file descriptor to a JS_Object.

       > Example
         Convert a file to a JS_Object.

             import Standard.Examples

             example_to_json = Examples.csv.to_js_object
    to_js_object : JS_Object
    to_js_object self =
        type_pair = ["type", "File"]
        cons_pair = ["constructor", "new"]
        JS_Object.from_pairs [type_pair, cons_pair, ["path", self.path]]

    ## GROUP Metadata
       ICON metadata
       Checks whether the file exists.

       > Example
         Check if a file exists.

             import Standard.Examples

             example_exists = Examples.csv.exists
    exists : Boolean
    exists self = @Builtin_Method "File.exists"

    ## GROUP Metadata
       ICON metadata
       Gets the size of a file in bytes.

       > Example
         Gets the size of a file.

             import Standard.Examples

             example_exists = Examples.csv.size
    size : Integer
    size self =
        File_Error.handle_java_exceptions self <| self.size_builtin

    ## GROUP Text
       ICON preparation
       Checks whether the file is within another path.

       Arguments:
       - parent: The path to check if self is contained within.

       > Example
         Check if a file is within another path.

             is_within = File.new "foo/bar" . starts_with (File.new "foo")
             is_not_within = File.new "foo/bar" . starts_with (File.new "f")
    starts_with : File -> Boolean
    starts_with self parent = @Builtin_Method "File.starts_with"

    ## GROUP Metadata
       ICON metadata
       Gets the creation time of a file.

       > Example
         Gets the creation time of a file.

             import Standard.Examples

             example_exists = Examples.csv.creation_time
    creation_time : Date_Time ! File_Error
    creation_time self =
        File_Error.handle_java_exceptions self <| self.creation_time_builtin

    ## GROUP Metadata
       ICON metadata
       Gets the last modified time of a file.

       > Example
         Gets the last modified time of a file.

             import Standard.Examples

             example_exists = Examples.csv.last_modified_time
    last_modified_time : Date_Time ! File_Error
    last_modified_time self =
        File_Error.handle_java_exceptions self <| self.last_modified_time_builtin

    ## ICON metadata
       Gets the POSIX permissions associated with the file.

       > Example
         Check if the file is readable by the user's group.

             import Standard.Examples

             example_permissions = Examples.csv.posix_permissions.group_read
    posix_permissions : File_Permissions
    posix_permissions self =
        File_Permissions.from_java_set self.posix_permissions_builtin

    ## GROUP Metadata
       ICON metadata
       Checks whether the file exists and is a directory.

       > Example
         Check if a file is a directory.

             import Standard.Examples

             example_is_directory = Examples.csv.is_directory
    is_directory : Boolean
    is_directory self = @Builtin_Method "File.is_directory"

    ## GROUP Output
       ICON folder_add
       Creates the directory represented by this file if it did not exist.

       It also creates parent directories if they did not exist.

       > Example
         Create a directory on the file system.

             import Standard.Examples

             example_is_directory =
                (Examples.data_dir / "my_directory") . create_directory
    create_directory : File ! File_Error
    create_directory self =
        Context.Output.if_enabled disabled_message="As writing is disabled, cannot create directory. Press the Write button ▶ to perform the operation." panic=False <|
            File_Error.handle_java_exceptions self self.create_directory_builtin . if_not_error self

    ## PRIVATE
       Creates the directory represented by this file if it did not exist.
    create_directory_builtin : Nothing
    create_directory_builtin self = @Builtin_Method "File.create_directory_builtin"

    ## GROUP Metadata
       ICON metadata
       Checks whether the file exists and is a regular file.

       ? Regular Files
         A regular file is one that does not have any special meaning to the
         operating system. Examples of files that are not regular are symlinks,
         pipes, devices, sockets and directories.

       > Example
         Check if a file is regular.

             import Standard.Examples

             example_is_regular_file = Examples.csv.is_regular_file
    is_regular_file : Boolean
    is_regular_file self = @Builtin_Method "File.is_regular_file"

    ## GROUP Metadata
       ICON metadata
       Checks whether it the file can be written to.

       ? Read-only Files
         If a file is read-only, it may still be possible to move or delete it,
         depending on the permissions associated with its parent directory.
    is_writable : Boolean
    is_writable self = @Builtin_Method "File.is_writable"

    ## GROUP Metadata
       ICON metadata
       Resolves the parent filesystem node of this file.

       The root directory has no parent, so this method will return `Nothing`.
       If the file is a relative path, the parent will be resolved relative to
       the current working directory.

       > Example
         Get the parent file of a file.

             import Standard.Examples

             example_parent = Examples.csv.parent
    parent : File | Nothing
    parent self = @Builtin_Method "File.parent"

    ## GROUP Metadata
       ICON metadata
       Returns the path of this file.

       > Example
         Get the path from a file.

             import Standard.Examples

             example_path = Examples.csv.path
    path : Text
    path self = @Builtin_Method "File.path"

    ## GROUP Metadata
       ICON metadata
       Returns the name of this file.

       > Example
         Get the name from a file.

             import Standard.Examples

             example_name = Examples.csv.name
    name : Text
    name self = @Builtin_Method "File.name"

    ## GROUP Metadata
       ICON metadata
       Returns the extension of the file.

       > Example
         Get the extension of a file.

             import Standard.Examples

             Examples.csv.extension == ".csv"
    extension : Text
    extension self =
        find_extension_from_name self.name

    ## ICON metadata
       Converts this file to an equivalent file represented with an absolute
       path.

       > Example
         Convert a file to an equivalent absolute path.

             import Standard.Examples

             example_absolute = Examples.csv.absolute
    absolute : File
    absolute self = @Builtin_Method "File.absolute"

    ## ICON metadata
       Checks is this file's path is absolute.

       > Example
         Check if a file is represented by an absolute path.

             import Standard.Examples

             example_is_absolute = Examples.csv.is_absolute
    is_absolute : Boolean
    is_absolute self = @Builtin_Method "File.is_absolute"

    ## ICON convert
       Normalizes the filepath.

       > Example
         Normalize a file path.

             import Standard.Examples

             example_normalize = Examples.csv.normalize
    normalize : File
    normalize self = @Builtin_Method "File.normalize"

    ## ICON data_output
       Deletes the file.

       Arguments:
       - recursive: If the target is a non-empty directory, it will only be
         removed if this is set to `True`. Defaults to `False`, meaning that the
         operation will fail if the directory is not empty. This option has no
         effect for files, data links or symlinks.

       > Example
         Create a file and then delete it.

             import Standard.Examples

             example_delete =
                 file = Examples.data_dir / "my_file"
                 file.write_text "hello"
                 file.delete
    delete : Boolean -> Nothing ! File_Error
    delete self (recursive : Boolean = False) -> Nothing ! File_Error =
        Context.Output.if_enabled disabled_message="As writing is disabled, cannot delete file. Press the Write button ▶ to perform the operation." panic=False <|
            File_Error.handle_java_exceptions self (self.delete_builtin recursive)

    ## ICON data_output
       Copies the file to the specified destination.

       Arguments:
       - destination: the destination to move the file to.
       - replace_existing: specifies if the operation should proceed if the
         destination file already exists. Defaults to `False`.
    copy_to : File_Like -> Boolean -> Any ! File_Error
    copy_to self (destination : File_Like) (replace_existing : Boolean = False) = Data_Link_Helpers.disallow_links_in_copy self destination <|
        Context.Output.if_enabled disabled_message="As writing is disabled, cannot copy file. Press the Write button ▶ to perform the operation." panic=False <|
            ## We defer the `Writable_File` conversion after the 'disallow links' check,
               because the conversion would already start resolving the data link too soon.
            destination_writable = Writable_File.from destination
            r = case destination_writable.file of
                _ : File -> local_file_copy self destination_writable.file replace_existing
                _ -> destination_writable.copy_from_local self replace_existing
            r.if_not_error destination_writable.file_for_return

    ## ICON data_output
       Moves the file to the specified destination.

       Arguments:
       - destination: the destination to move the file to.
       - replace_existing: specifies if the operation should proceed if the
         destination file already exists. Defaults to `False`.
    move_to : File_Like -> Boolean -> Any ! File_Error
    move_to self (destination : File_Like) (replace_existing : Boolean = False) = Data_Link_Helpers.disallow_links_in_move self destination <|
        Context.Output.if_enabled disabled_message="As writing is disabled, cannot move file. Press the Write button ▶ to perform the operation." panic=False <|
            ## We defer the `Writable_File` conversion after the 'disallow links' check,
               because the conversion would already start resolving the data link too soon.
            destination_writable = Writable_File.from destination
            r = case destination_writable.file of
                _ : File -> local_file_move self destination_writable.file replace_existing
                _ ->
                    r = destination_writable.copy_from_local self replace_existing
                    r.if_not_error <|
                        self.delete . if_not_error r
            r.if_not_error destination_writable.file_for_return

    ## ICON data_output
       Deletes the file if it exists on disk.

       Arguments:
       - recursive: If the target is a non-empty directory, it will only be
         removed if this is set to `True`. Defaults to `False`, meaning that the
         operation will fail if the directory is not empty. This option has no
         effect for files, data links or symlinks.

       > Example
         Delete a file if it exists on disk.

             import Standard.Examples

             example_del_if_exists = Examples.scratch_file.delete_if_exists
    delete_if_exists : Boolean -> Nothing ! File_Error
    delete_if_exists self (recursive : Boolean = False) = if self.exists then self.delete recursive else Nothing

    ## PRIVATE
       Reads first `n` bytes from the file (or less if the file is too small)
       and returns a vector of bytes.
    read_first_bytes : Integer -> Vector ! File_Error
    read_first_bytes self n =
        opts = [File_Access.Read]
        self.with_input_stream opts (_.read_n_bytes n)

    ## PRIVATE
       Reads last `n` bytes from the file (or less if the file is too small) and
       returns a vector of bytes.
    read_last_bytes : Integer -> Vector ! File_Error
    read_last_bytes self n =
        File_Error.handle_java_exceptions self <|
            Vector.from_polyglot_array (self.read_last_bytes_builtin n)

    ## GROUP Input
       ICON data_input
       Lists files contained in the directory denoted by this file.

       Arguments:
       - name_filter: A glob pattern that can be used to filter the returned
         files. If it is not specified, all files are returned.
       - recursive: Specifies whether the returned list of files should include
         also files from the subdirectories. If set to `False` (the default),
         only the immediate children of the listed directory are considered.

       The `name_filter` can contain the following special characters:
       - `"?"` - which matches a single filename character (so it will not match
         a `"/"`).
       - `"*"` - which matches any number of characters, but again does not
         cross directories.
       - `"**"` - which matches any number of characters and can cross
         directories.
       - `"\"` - can be used to escape the characters with special meaning; to
         get a single backslash, you need to specify it twice; you also need to
         keep in mind that the interpolating string literal also uses `"\"` as
         an escape sequence, so you need to type `'\\\\'` to get a single
         backslash for the glob pattern, unless you use the raw strings, where
         you only need to escape once: `"\\"`.
       - Brackets can be used to match exactly one character from some set of
         characters. For example `"[xy]"` matches `"x"` or `"y"`. Character
         ranges can also be specified: `"[a-z]"` matches any character from
         `"a"` to `"z"`. An exclamation mark can be used to negate the match,
         i.e. `"[!xz]"` will match any characters except for `"x"` and `"z"`.
         Moreover the ranges and single characters can be used together, so for
         example `"[a-cxy]"` will match `"a"`, `"b"`, `"c"`, `"x"` or `"y"`.
         Within the brackets, the special characters `"*"`, `"?"` and `"\"`
         stand for themselves instead of their special meanings.
       - Braces allow to specify multiple patterns (separated with a comma), one
         of which must be matched. For example: `"{abc,x*}"` will match either
         the name `"abc"` or any name starting with `"x"`. The groups cannot be
         nested.

       If `recursive` is set to True and a `name_filter` does not contain `**`,
       it will be automatically prefixed with `**/` to allow matching files in
       subdirectories.

       > Example
         List all files with ".md" or ".txt" extension in the example directory
         and any of its subdirectories.

             import Standard.Examples

             example_list_md_files =
                 Examples.data_dir.list name_filter="**.{txt,md}" recursive=True
    @name_filter File_Format.name_filter_widget
    list : Text -> Boolean -> Vector File
    list self name_filter:Text="" recursive:Boolean=False = 
        if Data_Link.is_data_link self then Data_Link_Helpers.interpret_data_link_target_as_file self . list name_filter=name_filter recursive=recursive else
            if self.is_directory.not then Error.throw (Illegal_Argument.Error "Cannot `list` a non-directory.") else
                all_files = if recursive then list_descendants self else self.list_immediate_children
                case name_filter of
                    "" -> all_files
                    _ ->
                        used_filter = if recursive.not || name_filter.contains "**" then name_filter else
                            (if name_filter.starts_with "*" then "*" else "{**/,}") + name_filter
                        matcher = File_Utils.matchPath "glob:"+used_filter
                        all_files.filter file->
                            pathStr = self.relativize file . path
                            File_Utils.matches matcher pathStr

    ## GROUP Metadata
       ICON metadata
       Checks if `self` is a descendant of `other`.
    is_descendant_of : File -> Boolean
    is_descendant_of self other = self.starts_with other

    ## ICON convert
       Transforms `child` to a relative path with respect to `self`.
    relativize : File -> Boolean
    relativize self child = @Builtin_Method "File.relativize"


    ## PRIVATE
       Utility function that lists immediate children of a directory.
    list_immediate_children : Vector File
    list_immediate_children self = Vector.from_polyglot_array (self.list_immediate_children_array)

    ## PRIVATE
       Return the path that this file represents.
    to_text : Text
    to_text self = self.path

    ## PRIVATE
       Convert to a display representation of this File.
    to_display_text : Text
    to_display_text self = self.to_text

## PRIVATE

   Utility function that returns all descendants of the provided file, including
   that file itself. If the file is not a directory, a list containing only
   itself is returned.
list_descendants : File -> Vector File
list_descendants file =
    Vector.build builder->
        go file =
            builder.append file
            case file.is_directory of
                True ->
                    children = file.list_immediate_children
                    children.each go
                False -> Nothing
        go file

## PRIVATE

   Gets a file corresponding to the current working directory of the
   program.
get_cwd : File
get_cwd = @Builtin_Method "File.get_cwd"

## PRIVATE

   Gets a file corresponding to the provided path.

   Arguments:
   - path: The path to obtain a file at.
get_file : Text -> File
get_file path = @Builtin_Method "File.get_file"

## PRIVATE
   Resolves the given path to a corresponding file location.

   If the provided path is relative, the behaviour depends on the context:
   - if the project is running in the Cloud, the path is resolved to a Cloud file,
     relative to the project's location.
   - if running locally, the path is resolved to a local file, relative to the
     current working directory.
resolve_path (path : Text) -> File | Enso_File =
    local_file = get_file path
    # Absolute files always resolve to themselves.
    if local_file.is_absolute then local_file else
        case Enso_File.cloud_project_parent_directory of
            Nothing -> local_file
            base_cloud_directory -> base_cloud_directory / path

## PRIVATE
get_child_widget : File -> Widget
get_child_widget file =
    if file.exists.not then Nothing else
        if file.is_directory.not then Nothing else
            children = file.list
            options = children.map c-> Option c.name c.name.pretty
            Widget.Single_Choice values=options display=Display.Always

## PRIVATE
find_extension_from_name : Text -> Text
find_extension_from_name name =
    extension = name.drop (..Before_Last ".")
    if extension == "." then "" else extension

## PRIVATE
   Convert from a Text to a File.
File.from (that:Text) = File.new that

## PRIVATE
file_as_java : File -> Java_File
file_as_java (file : File) = Java_File.new file.absolute.normalize.path

## PRIVATE
File_Like.from (that : File) = File_Like.Value that

## PRIVATE
Writable_File.from (that : File) = if Data_Link.is_data_link that then Data_Link_Helpers.interpret_data_link_as_writable_file that else
    Writable_File.Value that.absolute.normalize Local_File_Write_Strategy.instance

## PRIVATE
local_file_copy (source : File) (destination : File) (replace_existing : Boolean) -> Nothing =
    File_Error.handle_java_exceptions source <|
        copy_options = if replace_existing then [StandardCopyOption.REPLACE_EXISTING.to_text] else []
        source.copy_builtin destination copy_options

## PRIVATE
local_file_move (source : File) (destination : File) (replace_existing : Boolean) -> Nothing =
    File_Error.handle_java_exceptions source <|
        copy_options = if replace_existing then [StandardCopyOption.REPLACE_EXISTING.to_text] else []
        source.move_builtin destination copy_options

# PRIVATE
type File_System_SPI
    private Entry protocol:Text typ

    new protocol:Text typ = File_System_SPI.Entry protocol typ

    private get_type protocol:Text _:Boolean =
        vec = Self.get_types . filter (_.protocol == protocol)
        if vec . not_empty then vec.first else Nothing

    private get_types _:Boolean =
        Meta.lookup_services File_System_SPI