file

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 30, 2024 License: MIT Imports: 18 Imported by: 0

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', ....]
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)
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'])
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

View Source 
const ModuleName = "file"

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

Variables

View Source 
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 added in v0.0.15 

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

FileStat represents the file information.

func (*FileStat) Struct added in v0.0.15 

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.