file

README

file

file provides functions to interact with the file system. The library is inspired by file helpers from Amoy.

Functions

trim_bom(rd) string

Removes the Byte Order Mark (BOM) from a byte literal string or bytes.

Parameters

name	type	description
rd	`string	byes`

Examples

basic

Removes the Byte Order Mark (BOM) from a string.

load("file", "trim_bom")
s = b'\xef\xbb\xbfhello'
print(trim_bom(s))
# Output: hello

count_lines(name) int

Counts the total lines in a file located at the provided path.

Parameters

name	type	description
name	string	The path of the file whose lines are to be counted

Examples

basic

Count the lines of a file.

load("file", "count_lines")
name = 'path/to/file.txt'
print(count_lines(name))
# Output: 10

head_lines(name, n) []string

Returns the first 'n' lines of a file.

Parameters

name	type	description
name	string	The path of the file
n	int	The number of lines from the top to be returned

Examples

basic

Get the top 10 lines of a file.

load('file', 'head_lines')
print(head_lines('path/to/file.txt', 10))
# Output: ['line1', 'line2', ... 'line10']

tail_lines(name, n) []string

Returns the last 'n' lines of a file.

Parameters

name	type	description
name	string	The path of the file
n	int	The number of lines from the bottom to be returned

Examples

basic

Get the bottom 10 lines of a file.

load('file', 'tail_lines')
print(tail_lines('path/to/file.txt', 10))
# Output: ['line91', 'line92', ... 'line100']

read_bytes(name)

Reads a file and returns its contents as bytes.

Parameters

name	type	description
name	string	The path of the file to be read

Examples

basic

Read a file in bytes.

load('file', 'read_bytes')
print(read_bytes('path/to/file.txt'))
# Output: b'file_content'

read_string(name)

Reads a file and returns its contents as string.

Parameters

name	type	description
name	string	The path of the file to be read

Examples

basic

Read a file in string.

load('file', 'read_string')
print(read_string('path/to/file.txt'))
# Output: 'file_content'

read_lines(name)

Reads a file and returns its contents as a list of lines.

Parameters

name	type	description
name	string	The path of the file to be read

Examples

basic

Get lines of a file in a list.

load('file', 'read_lines')
print(read_lines('path/to/file.txt'))
# Output: ['line1', 'line2', 'line3', ....]

read_json(name) dict

Reads a file and decodes its contents as JSON, returning the corresponding Starlark object (dict or any types).

Parameters

name	type	description
name	string	The path of the JSON file to be read

Examples

basic

Read a JSON file.

load('file', 'read_json')
data = read_json('path/to/file.json')
print(data)
# Output: {'key': 'value', 'array': [1, 2, 3]}

read_jsonl(name) list

Reads a file with each line containing a JSON object and returns a list of Starlark objects.

Parameters

name	type	description
name	string	The path of the JSONL file to be read

Examples

basic

Read a JSONL file.

load('file', 'read_jsonl')
data = read_jsonl('path/to/file.jsonl')
print(data)
# Output: [{'key1': 'value1'}, {'key2': 'value2'}]

write_bytes(name, data)

Writes/overwrites bytes or a byte literal string to a file. If the file isn't present, a new file would be created.

Parameters

name	type	description
name	string	The path of the file to be written to
data	string	The byte literal string or bytes to be written to the file

Examples

basic

Write a byte string to a file.

load('file', 'write_bytes')
name = 'new_file.txt'
data = b'Hello, This is a new file.'
write_bytes(name, data)

write_string(name, data)

Writes/overwrites a string to a file. If the file isn't present, a new file would be created.

Parameters

name	type	description
name	string	The path of the file to be written to
data	string	The string to be written to the file

Examples

basic

Write a string to a file.

load('file', 'write_string')
write_string('new_file.txt', 'Hello, This is a new file.')

write_lines(name, data)

Writes/overwrites a list, tuple or set of lines to a file. If the file isn't present, a new file would be created.

Parameters

name	type	description
name	string	The path of the file to be written to
data	`list	set

Examples

List

Write a list of lines to a file.

load('file', 'write_lines')
lines = ['This is line1', 'This is line2', 'This is line3']
write_lines('new_file.txt', lines)

write_json(name, data)

Writes the given Starlark object as JSON to a file. If the file exists, it will be overwritten.

Parameters

name	type	description
name	string	The path of the file to be written to
data	`dict	list

Examples

basic

Write a dictionary as JSON to a file.

load('file', 'write_json')
data = {"key": "value", "array": [1, 2, 3]}
write_json('new_file.json', data)

write_jsonl(name, data)

Writes the given data as JSON lines to a file. If the file exists, it will be overwritten.

Parameters

name	type	description
name	string	The path of the file to be written to
data	`list	set

Examples

basic

Write a list of JSON objects to a file as JSONL.

load('file', 'write_jsonl')
data = [{"key1": "value1"}, {"key2": "value2"}]
write_jsonl('new_file.jsonl', data)

append_bytes(name, data)

Appends bytes or a byte literal string to a file. If the file isn't present, a new file would be created.

Parameters

name	type	description
name	string	The path of the file to be written to
data	string	The byte literal string or bytes to be appended to the file

Examples

basic

Append a byte string to a file.

load('file', 'append_bytes')
append_bytes('existing_file.txt', b'Hello, This is appended data.')

append_string(name, data)

Appends a string to a file. If the file isn't present, a new file would be created.

Parameters

name	type	description
name	string	The path of the file to be written to
data	string	The string to be appended to the file

Examples

basic

Append a string to a file.

load('file', 'append_string')
append_string('existing_file.txt', 'Hello, This is appended data.')

append_lines(name, data)

Appends a list, tuple or set of lines to a file. If the file isn't present, a new file would be created.

Parameters

name	type	description
name	string	The path of the file to be written to
data	`list	set

Examples

basic

Append a list of lines to a file.

load('file', 'append_lines')
append_lines('existing_file.txt', ['This is line1', 'This is line2', 'This is line3'])

append_json(name, data)

Appends the given Starlark object as JSON to a file. If the file does not exist, it will be created.

Parameters

name	type	description
name	string	The path of the file to be appended to
data	`dict	list

Examples

basic

Append a dictionary as JSON to a file.

load('file', 'append_json')
data = {"key": "value"}
append_json('existing_file.json', data)

append_jsonl(name, data)

Appends the given data as JSON lines to a file. If the file does not exist, it will be created.

Parameters

name	type	description
name	string	The path of the file to be appended to
data	`list	set

Examples

basic

Append a list of JSON objects to a file as JSONL.

load('file', 'append_jsonl')
data = [{"key1": "value1"}, {"key2": "value2"}]
append_jsonl('existing_file.jsonl', data)

stat(name, follow=False) FileStat

Returns a FileStat object representing information about the given file or directory.

Parameters

name	type	description
name	string	The path of the file or directory.
follow	bool	If true, symbolic links are followed.

Examples

file information

Retrieve information about a file.

load('file', 'stat')
info = stat('path/to/file.txt')
print(info.name, info.size, info.type)
# Output: file.txt 3759 file

directory information

Retrieve information about a directory.

load('file', 'stat')
info = stat('path/to/folder', follow=True)
print(info.name, info.size, info.type)
# Output: folder 448 dir

copyfile(src, dst, overwrite=False) string

Copies a file from source to destination, and returns the destination file path. If the destination exists and overwrite is set to False, an error is returned. If the destination is a directory, the file is copied into that directory with its original filename. Symbolic links are followed. Mode, access, and modification times are preserved.

Parameters

name	type	description
src	string	The path of the source file to be copied.
dst	string	The path of the destination file or directory. The parent directory must exist.
overwrite	bool	If true, allows overwriting the destination file if it exists. Defaults to False.

Examples

basic copy

Copy a file to a new location without overwrite.

load('file', 'copyfile')
src = 'path/to/source.txt'
dst = 'path/to/destination.txt'
copyfile(src, dst)
# The file at 'path/to/source.txt' is copied to 'path/to/destination.txt'

overwrite copy

Copy a file to a new location with overwrite enabled.

load('file', 'copyfile')
src = 'path/to/source.txt'
dst = 'path/to/existing_destination.txt'
copyfile(src, dst, overwrite=True)
# The file at 'path/to/source.txt' is copied to 'path/to/existing_destination.txt', overwriting it.

copy to directory

Copy a file into a directory.

load('file', 'copyfile')
src = 'path/to/source.txt'
dst = 'path/to/directory'
copyfile(src, dst)
# The file at 'path/to/source.txt' is copied into 'path/to/directory' with its original filename.

Types

FileStat

Represents information about a file.

Fields

name	type	description
name	string	The name of the file.
path	string	The full path of the file.
ext	string	The file extension.
size	int	The size of the file in bytes.
type	string	The type of the file: file for regular file, dir for directory, symlink for symbolic link, fifo for FIFO pipe, socket for network socket, char for character device file, block for block device file, irregular for irregular file type, unknown for unknown file type.
modified	time.Time	The last modified time of the file.
get_md5()	function	Returns the MD5 hash of the file contents.
get_sha1()	function	Returns the SHA-1 hash of the file contents.
get_sha256()	function	Returns the SHA-256 hash of the file contents.
get_sha512()	function	Returns the SHA-512 hash of the file contents.

Documentation

Overview

Package file defines functions that manipulate files, it's inspired by file helpers from Amoy.

Index

• Constants
• Variables
• func AppendFileBytes(path string, data []byte) error
• func AppendFileLines(path string, lines []string) error
• func AppendFileString(path string, content string) error
• func CountFileLines(path string) (count int, err error)
• func LoadModule() (starlark.StringDict, error)
• func ReadFileBytes(path string) ([]byte, error)
• func ReadFileLines(path string) (lines []string, err error)
• func ReadFileString(path string) (string, error)
• func ReadFirstLines(path string, n int) (lines []string, err error)
• func ReadLastLines(path string, n int) (lines []string, err error)
• func TrimUTF8BOM(b []byte) []byte
• func WriteFileBytes(path string, data []byte) error
• func WriteFileLines(path string, lines []string) error
• func WriteFileString(path string, content string) error
• type FileStat
  • func (f *FileStat) Struct() *starlarkstruct.Struct
• type LineFunc

Constants

const ModuleName = "file"

ModuleName defines the expected name for this Module when used in starlark's load() function, eg: load('file', 'trim_bom')

Variables

var (
	// QuitRead indicates the arbitrary error means to quit from reading.
	QuitRead = errors.New("file: quit read by line")
)

Functions

func AppendFileBytes

func AppendFileBytes(path string, data []byte) error

AppendFileBytes writes the given data to the end of a file.

func AppendFileLines

func AppendFileLines(path string, lines []string) error

AppendFileLines appends the given lines to the end of a text file.

func AppendFileString

func AppendFileString(path string, content string) error

AppendFileString appends the given content string to the end of a file.

func CountFileLines

func CountFileLines(path string) (count int, err error)

CountFileLines counts all lines from the given file (the line ending chars are not included).

func LoadModule

func LoadModule() (starlark.StringDict, error)

LoadModule loads the file module. It is concurrency-safe and idempotent.

func ReadFileBytes

func ReadFileBytes(path string) ([]byte, error)

ReadFileBytes reads the whole named file and returns the contents. It's a sugar actually, simply calls os.ReadFile like ioutil.ReadFile does since Go 1.16.

func ReadFileLines

func ReadFileLines(path string) (lines []string, err error)

ReadFileLines reads all lines from the given file (the line ending chars are not included).

func ReadFileString

func ReadFileString(path string) (string, error)

ReadFileString reads the whole named file and returns the contents as a string.

func ReadFirstLines

func ReadFirstLines(path string, n int) (lines []string, err error)

ReadFirstLines reads the top n lines from the given file (the line ending chars are not included), or lesser lines if the given file doesn't contain enough line ending chars.

func ReadLastLines

func ReadLastLines(path string, n int) (lines []string, err error)

ReadLastLines reads the bottom n lines from the given file (the line ending chars are not included), or lesser lines if the given file doesn't contain enough line ending chars.

func TrimUTF8BOM

func TrimUTF8BOM(b []byte) []byte

TrimUTF8BOM removes the leading UTF-8 byte order mark from bytes.

func WriteFileBytes

func WriteFileBytes(path string, data []byte) error

WriteFileBytes writes the given data into a file.

func WriteFileLines

func WriteFileLines(path string, lines []string) error

WriteFileLines writes the given lines as a text file.

func WriteFileString

func WriteFileString(path string, content string) error

WriteFileString writes the given content string into a file.

Types

type FileStat

type FileStat struct {
	os.FileInfo
	// contains filtered or unexported fields
}

FileStat represents the file information.

func (*FileStat) Struct

func (f *FileStat) Struct() *starlarkstruct.Struct

Struct returns a starlark struct with file information.

type LineFunc

type LineFunc func(line string) (err error)

LineFunc stands for a handler for each line string.