# Files

Functions for working with files and directories are described here.

* [AppendFile( str filename, buf | str data )](#appendfile-str-filename-buf-or-str-data)
* [ChDir( str dirname )](#chdir-str-dirname)
* [ChMode( str name, int mode )](#chmode-str-name-int-mode)
* [CloseFile( file f )](#closefile-file-f)
* [CopyFile( str src, str dest ) int](#copyfile-str-src-str-dest-int)
* [CreateDir( str dirname )](#createdir-str-dirname)
* [CreateFile( str name, bool trunc )](#createfile-str-name-bool-trunc)
* [ExistFile( str name ) bool](#existfile-str-name-bool)
* [FileInfo( file f ) finfo](#fileinfo-file-f-finfo)
* [FileInfo( str name ) finfo](#fileinfo-str-name-finfo)
* [FileMode( str name ) int](#filemode-str-name-int)
* [GetCurDir() str](#getcurdir-str)
* [IsEmptyDir( str path ) bool](#isemptydir-str-path-bool)
* [Md5File( str filename ) str](#md-5-file-str-filename-str)
* [obj( finfo fi ) obj](#obj-finfo-fi-obj)
* [OpenFile( str filename, int flags ) file](#openfile-str-filename-int-flags-file)
* [Read( file f, int size ) buf](#read-file-f-int-size-buf)
* [ReadDir( str dirname ) arr.finfo](#readdir-str-dirname-arr-finfo)
* [ReadDir( str dirname, int flags, str pattern ) arr.finfo](#readdir-str-dirname-int-flags-str-pattern-arr-finfo)
* [ReadDir( str dirname, int flags, arr.str patterns, arr.str ignore ) arr.finfo](#readdir-str-dirname-int-flags-arr-str-patterns-arr-str-ignore-arr-finfo)
* [ReadFile( str filename ) str](#readfile-str-filename-str)
* [ReadFile( str filename, buf out ) buf](#readfile-str-filename-buf-out-buf)
* [ReadFile( str filename, int offset, int length ) buf](#readfile-str-filename-int-offset-int-length-buf)
* [Remove( str name )](#remove-str-name)
* [RemoveDir( str dirname )](#removedir-str-dirname)
* [Rename( str oldpath, str newpath )](#rename-str-oldpath-str-newpath)
* [SetFileTime( str name, time modtime )](#setfiletime-str-name-time-modtime)
* [SetPos( file f, int off, int whence ) int](#setpos-file-f-int-off-int-whence-int)
* [Sha256File( str filename ) str](#sha-256-file-str-filename-str)
* [TempDir() str](#tempdir-str)
* [TempDir( str path, str prefix ) str](#tempdir-str-path-str-prefix-str)
* [Write( file f, buf b ) file](#write-file-f-buf-b-file)
* [WriteFile( str filename, buf | str data )](#writefile-str-filename-buf-or-str-data)

## Types

### finfo

The *finfo* is used for getting information about a file and has the following fields:

* **str Name** - base name of the file
* **int Size** - length in bytes for regular files
* **int Mode** - file's mode and permission bits
* **time Time** - last modification time
* **bool IsDir** - true if it is a directory
* **str Dir** - directory where the file is located. This field is only filled when calling the function [ReadDir(str, int, str)](#readdir-str-dirname-int-flags-str-pattern-arr-finfo)

### file

The *file* type is used in functions that work with the open file descriptor.

## Functions

### AppendFile(str filename, buf|str data)

The *AppendFile* function appends data of *buf* variable or a string to a file named by *filename*. If the file does not exist, *AppendFile* creates it with 0644 permissions.

### ChDir(str dirname)

The *ChDir* function changes the current directory.

### ChMode(str name, int mode)

The *ChMode* function changes the attributes of the file.

### CloseFile(file f)

The *CloseFile* function closes the file descriptor that was opened with the **OpenFile** function.

### CopyFile(str src, str dest) int

The *CopyFile* function copies *src* file to *dest* file. If *dest* file exists it is overwritten. The file attributes are preserved when copying. The function returns the number of copied bytes.

### CreateDir(str dirname)

The *CreateDir* function creates a directory named *dirname*, along with any necessary parents. If *dirname* is already a directory, *CreateDir* does nothing.

### CreateFile(str name, bool trunc)

The *CreateFile* function creates a file with the specified name. If the *trunc* parameter is *true* and the file already exists, its size becomes 0.

### ExistFile(str name) bool

The *ExistFile* function returns *true* if the specified file or directory exists. Otherwise, it returns *false*.

### FileInfo(file f) finfo

The *FileInfo* function receives information about the specified file and returns the *finfo* structure. The file must be opened using the **OpenFile** function.

### FileInfo(str name) finfo

The *FileInfo* function gets information about the named file and returns *finfo* structure.

### FileMode(str name) int

The *FileMode* function returns the file attributes.

### GetCurDir() str

The *GetCurDir* function returns the current directory.

### IsEmptyDir(str path) bool

The *IsEmptyDir* function returns *true* if the specified directory is empty. Otherwise, it returns *false*.

### Md5File(str filename) str

The *Md5File* function returns the MD5 hash of the specified file as a hex string.

### obj(finfo fi) obj

The *obj* function converts a variable of finfo type into an object. The resulting object has fields: *name, size, mode, time, isdir, dir*.

### OpenFile(str filename, int flags) file

The *OpenFile* function opens the specified file and returns a variable of *file* type with an open file descriptor. After working with the file, the open file descriptor must be closed using the **CloseFile** function. The *flags* parameter may be zero or a combination of the following flags:

* *CREATE* - if the file does not exist, it will be created.
* *TRUNC* - file will be truncated to zero length after opening.
* *READONLY* - the file will be open for reading only.

```go
    file f = OpenFile(fname, CREATE)
    Write(f, buf("some test string"))
    SetPos(f, -15, 1)
    buf b &= Read(f, 5)
    CloseFile(f)
```

### Read(file f, int size) buf

The *Read* function reads the *size* number of bytes from the current position in the file that was opened using the **OpenFile** function. The function returns a variable of the *buf* type, which contains the read data.

### ReadDir(str dirname) arr.finfo

The *ReadDir* function reads the directory named by dirname and returns a list of directories and files entries.

### ReadDir(str dirname, int flags, str pattern) arr.finfo

The *ReadDir* function reads the *dirname* directory with the specified name and returns the list of its subdirectories and files according to the specified parameters. The *flags* parameter can be a combination of the following flags:

* **RECURSIVE** - In this case there will be a recursive search for all subdirectories.
* **ONLYFILES** - The returned array will contain only files.
* **ONLYDIRS** - The returned array will contain only directories.
* **REGEXP** - The *pattern* parameter contains a regular expression for matching file names.

If you specify the **ONLYFILES** and **ONLYDIRS** flags at the same time, the files and directories will be searched.

The *pattern* parameter can contain a wildcard for files or a regular expression. In this case, the files and directories that match the specified pattern will be returned. The wildcard can contain the following characters:

* '\*' - matches any sequence of non-separator characters
* '?' - matches any single non-separator character

```go
for item in ReadDir(ftemp, RECURSIVE, `*fold*`) {
    ret += item.Name
}
for item in ReadDir(ftemp, RECURSIVE | ONLYFILES | REGEXP, `.*\.pdf`) {
    ret += item.Name
}
```

### ReadDir(str dirname, int flags, arr.str patterns, arr.str ignore) arr.finfo

The *ReadDir* function reads the *dirname* directory with the specified name and returns the list of its subdirectories and files according to the specified parameters. The parameter *flags* is described above. The *patterns* parameter is an array of strings and may contain file masks or regular expressions. The *ignore* parameter also contains file wildcards or regular expressions, but such files or directories will be skipped. If you want to specify a regular expression in these arrays, enclose it between **'/'** characters.

```go
arr.str aignore = {`/txt/`, `*.pak`}
arr.str amatch = {`/\d+/`, `*.p?`, `/di/`}.
for item in ReadDir(ftemp, RECURSIVE, amatch, aignore) {
    ret += item.Name
}
```

### ReadFile(str filename) str

The *ReadFile* function reads the specified file and returns the contents as a string.

### ReadFile(str filename, buf out) buf

The *ReadFile* function reads the file named by *filename* to the *buf* variable *out* and returns it.

### ReadFile(str filename, int offset, int length) buf

The *ReadFile* function reads data from the *filename* file starting at offset *offset* and length *length*. If *offset* is less than zero, then the offset is counted from the end to the beginning of the file.

### Remove(str name)

The *Remove* function removes a file or an empty directory.

### RemoveDir(str dirname)

The *RemoveDir* function removes *dirname* directory and any children it contains.

### Rename(str oldpath, str newpath)

The *Rename* function renames (moves) *oldpath* to *newpath*. If *newpath* already exists and is not a directory, *Rename* replaces it.

### SetFileTime(str name, time modtime)

The *SetFileTime* function changes the modification time of the named file.

### SetPos(file f, int off, int whence) int

The *SetPos* function sets the current position in the file for read or write operations. The file must be opened with the **OpenFile** function. The function returns the offset of the new position. The *whence* parameter can take the following values:

* *0* - the *off* offset is specified from the beginning of file.
* *1* - the *off* offset is specified from the current position.
* *2* - the *off* offset is specified from the end of a file.

### Sha256File(str filename) str

The *Sha256File* function returns the SHA256 hash of the specified file as a hex string.

### TempDir() str

The *TempDir* function returns the default temporary directory.

### TempDir(str path, str prefix) str

The *TempDir* function creates a new temporary directory in the directory *path* with a name beginning with *prefix* and returns the path of the new directory. If *path* is the empty string, *TempDir* uses the default temporary directory.

### Write(file f, buf b) file

The *Write* function writes data from a variable of the *buf* type to a file that was opened using the **OpenFile** function. The function returns the *f* parameter.

### WriteFile(str filename, buf|str data)

The *WriteFile* function writes data of *buf* variable or a string to a file named by *filename*. If the file does not exist, *WriteFile* creates it with 0777 permissions, otherwise the file is truncated before writing.