tsfio

package module
v1.5.1 Latest Latest
Warning

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

 Go to latest Published: Dec 3, 2023 License: AGPL-3.0 Imports: 9 Imported by: 5

README

tsfio

Go Report Card CodeFactor OSS Lifecycle

PkgGoDev GitHub go.mod Go version Libraries.io dependency status for GitHub repo

GitHub release (latest by date) GitHub last commit GitHub commit activity GitHub code size in bytes GitHub Top Language GitHub

Go package with a simple API for file input output. It is a supplement to the standard library and supplies additional functions for file input output and string operations, e.g., appending one file to another file.

  • Simple: Without configuration, just function calls, and default flags are used
  • Resilient: File input output on Linux and Windows system directories or files are blocked (see inval_unix.go and inval_win.go)
  • Tested: Unit tests with a high code coverage
  • Dependencies: Only depends on the Go Standard Library and tserr

Defaults

All file input output operations on Linux and Windows system directories or files are blocked (see inval_unix.go and inval_win.go) and an error is returned. All operations expect a directory or a regular file, return an error otherwise. Default flags and file mode is used when opening files, creating files or directories and when writing to files (with exceptions documented in the function descriptions)

  • Files are opened read-write (os.O_RDWR).
  • Data is appended when writing to file (os.O_APPEND).
  • A file is created if it does not exist (os.O_CREATE).
  • File mode and permission bits are 0644.
  • Directory mode and permissions bits are 0755.

If an API call is not successful, a tserr error in JSON format is returned.

Usage

In the Go app, the package is imported with

import "github.com/thorstenrie/tsfio"

A Filename is the name of a regular file and may contain its path. A Directory is the name of a directory and may contain its path

type Filename string
type Directory string

CheckFile performs checks on Filename f and CheckDir performs checks on Directory d

func CheckFile(f Filename) error
func CheckDir(d Directory) error

All external functions contain a CheckFile or CheckDir call at the beginning.

func OpenFile(fn Filename) (*os.File, error)
func CloseFile(f *os.File) error
func WriteStr(fn Filename, s string) error
func WriteSingleStr(fn Filename, s string) error
func TouchFile(fn Filename) error
func ReadFile(f Filename) ([]byte, error)
func AppendFile(a *Append) error
func ExistsFile(fn Filename) (bool, error)
func RemoveFile(f Filename) error
func ResetFile(fn Filename) error
func CreateDir(d Directory) error
func FileSize(fn Filename) (int64, error)

With Printable functions, non-printable runes can be removed from strings and runes

func Printable(a string) string
func IsPrintable(a []string) (bool, error)
func RuneToPrintable(r rune) string

With golden file functions, golden files can be created and test cases evaluated. Golden files can be used in unit tests. The expected output is stored in a golden file. The actual output data will be compared with the golden file. The test fails if there is a difference in actual output and golden file.

func GoldenFilePath(name string) (Filename, error)
func CreateGoldenFile(tc *Testcase) error
func EvalGoldenFile(tc *Testcase) error

With normalization functions, new lines in byte slices or strings are normalized to the Unix representation of a new line as line feed LF (0x0A). Therefore, Windows new lines CR LF (0x0D 0x0A) are replaced by Unix new lines LF (0x0A). Also, Mac new lines CR (0x0D) are replaced by Unix new lines LF (0x0A).

func NormNewlinesBytes(i []byte) ([]byte, error)
func NormNewlinesStr(i string) string

Example

package main

import (
	"fmt"
	"os"

	"github.com/thorstenrie/tsfio"
)

func main() {
	f1, _ := os.CreateTemp("", "foo")
	fn1 := tsfio.Filename(f1.Name())

	f2, _ := os.CreateTemp("", "foo")
	fn2 := tsfio.Filename(f2.Name())

	tsfio.RemoveFile(fn1)
	b, _ := tsfio.ExistsFile(fn1)
	fmt.Println(b)

	tsfio.TouchFile(fn1)
	b, _ = tsfio.ExistsFile(fn1)
	fmt.Println(b)

	tsfio.WriteStr(fn1, "foo")
	tsfio.WriteStr(fn1, "foo")
	c, _ := tsfio.ReadFile(fn1)
	fmt.Println(string(c))

	tsfio.WriteStr(fn2, "foo")
	tsfio.AppendFile(&tsfio.Append{FileA: fn1, FileI: fn2})
	c, _ = tsfio.ReadFile(fn1)
	fmt.Println(string(c))

	fs, _ := tsfio.FileSize(fn1)
	fmt.Println(fs)

	tsfio.WriteSingleStr(fn1, "foo")
	c, _ = tsfio.ReadFile(fn1)
	fmt.Println(string(c))

	tsfio.ResetFile(fn1)
	c, _ = tsfio.ReadFile(fn1)
	fmt.Println(string(c))
}

Go Playground

Output

false
true
foofoo
foofoofoo
9
foo

Godoc

Go Report Card

Open Source Insights

Documentation

Overview

Package tsfio provides a simple API for file input output based on the standard library.

The tsfio package is a supplement to the standard library and supplies additional functions for file input output operations, e.g., appending one file to another file. Also, file input output operations on Linux and Windows system directories or files are blocked (see inval_unix.go and inval_win.go) and an error is returned. All operations expect a directory or a regular file, return an error otherwise. Default flags and file mode is used when opening files, creating files or directories and when writing to files (with exceptions documented in the function descriptions)

  • Files are opened read-write (os.O_RDWR).
  • Data is appended when writing to file (os.O_APPEND).
  • A file is created if it does not exist (os.O_CREATE).
  • File mode and permission bits are 0644.
  • Directory mode and permissions bits are 0755.

If an API call is not successful, a tserr error in JSON format is returned.

With Printable functions, non-printable runes can be removed from strings and runes. With golden file functions, golden files can be created and test cases evaluated. Golden files can be used in unit tests. The expected output is stored in a golden file. The actual output data will be compared with the golden file. The test fails if there is a difference in actual output and golden file. With normalization functions, new lines in byte slices or strings are normalized to the Unix representation of a new line as line feed LF (0x0A). Therefore, Windows new lines CR LF (0x0D 0x0A) are replaced by Unix new lines LF (0x0A). Also, Mac new lines CR (0x0D) are replaced by Unix new lines LF (0x0A).

Copyright (c) 2023 thorstenrie. All Rights Reserved. Use is governed with GNU Affero General Public Licence v3.0 that can be found in the LICENSE file.

Copyright (c) 2023 thorstenrie. All Rights Reserved. Use is governed with GNU Affero General Public Licence v3.0 that can be found in the LICENSE file.

Copyright (c) 2023 thorstenrie. All Rights Reserved. Use is governed with GNU Affero General Public Licence v3.0 that can be found in the LICENSE file.

Copyright (c) 2023 thorstenrie. All Rights Reserved. Use is governed with GNU Affero General Public Licence v3.0 that can be found in the LICENSE file.

Copyright (c) 2023 thorstenrie. All Rights Reserved. Use is governed with GNU Affero General Public Licence v3.0 that can be found in the LICENSE file.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AppendFile 

func AppendFile(a *Append) error

AppendFile appends a file to another file. It receives a pointer to struct Append which holds fileA, the file to be extended by contents of fileI and fileI, the input file, holding the contents to be appended to fileA. As result, fileA holds its original content extended by the contents of fileI, and fileI remains as before. If fileA does not exist, it is created as empty file and as result will hold the contents of fileI. If fileI does not exist, it returns an error. AppendFile returns an error, if any.

func CheckDir 

func CheckDir(d Directory) error

CheckDir performs checks on directory d and returns an error if

  • d is an empty string
  • d contains a blocked directory or filename
  • d is an existing file, not a directory
  • os.Stat returns an error when retrieving FileInfo

Otherwise it returns nil.

func CheckFile 

func CheckFile(f Filename) error

CheckFile performs checks on file f and returns an error if

  • f is an empty string
  • f contains a blocked directory or filename
  • f is an existing directory, not a file
  • os.Stat returns an error when retrieving FileInfo

Otherwise it returns nil.

func CloseFile 

func CloseFile(f *os.File) error

CloseFile closes f and f is unusable for file input output. An error is returned if f has already been closed.

func CreateDir 

func CreateDir(d Directory) error

CreateDir creates a directory named d with any necessary parents. If d already exists as directory, it does nothing and returns nil. It returns an error, if there is any.

func CreateGoldenFile added in v1.3.0 

func CreateGoldenFile(tc *Testcase) error

CreateGoldenFile creates a golden file provided by the testcase name. The data in the testcase is written to the golden file. The golden file is stored in the default golden files directory testdata/ and has the default golden file type .golden.

func EvalGoldenFile added in v1.3.0 

func EvalGoldenFile(tc *Testcase) error

EvalGoldenFile evaluates the testcase if it equals the test data from the golden file provided by the testcase name. It returns an error if the testcase data does not equal the contents of the golden file. The golden file must reside in the default golden files directory testdata/ with the default golden file type .golden.

func ExistsDir added in v1.5.0 

func ExistsDir(dn Directory) (bool, error)

ExistsDir returns true if directory dn exists, returns false otherwise. It returns false and an error if there is any. If dn is a file, ExistsDir returns false and an error.

func ExistsFile 

func ExistsFile(fn Filename) (bool, error)

ExistsFile returns true if file fn exists, returns false otherwise. It returns false and an error if there is any. If fn is a directory, ExistsFile returns false and an error.

func FileSize added in v1.1.0 

func FileSize(fn Filename) (int64, error)

FileSize returns the length in bytes for the regular file fn. If fn is a blocked filename, a directory or if FileInfo for fn cannot be retrieved, it returns 0 and an error.

func IsPrintable added in v1.3.0 

func IsPrintable(a []string) (bool, error)

IsPrintable returns true, if slice of strings a only consists of printable strings. If one or more strings of slice contain a non-printable character, it returns false. If a is nil or has zero length, it returns false and an error.

func NormNewlinesBytes added in v1.4.0 

func NormNewlinesBytes(i []byte) ([]byte, error)

NormNewlinesBytes normalizes new lines in the byte slice i. New lines are normalized to the Unix representation of a new line as line feed LF (0x0A). Therefore, Windows new lines CR LF (0x0D 0x0A) are replaced by Unix new lines LF (0x0A). Also, Mac new lines CR (0x0D) are replaced by Unix new lines LF (0x0A). It returns a normalized copy of i. If i is nil, it returns an error.

func NormNewlinesStr added in v1.4.0 

func NormNewlinesStr(i string) string

NormNewlinesStr normalizes new lines in the string i. New lines are normalized to the Unix representation of a new line as line feed LF (0x0A). Therefore, Windows new lines CR LF (0x0D 0x0A) are replaced by Unix new lines LF (0x0A). Also, Mac new lines CR (0x0D) are replaced by Unix new lines LF (0x0A). It returns a normalized copy of i.

func OpenFile 

func OpenFile(fn Filename) (*os.File, error)

OpenFile opens the named file fn with default flags and permission bits. If the file does not exist, it is created. If the directory to the file does not exist, the file will not be created and OpenFile returns an error. If opened successfully, the file is returned and can be used for file input output and error is nil.

func Printable added in v1.2.0 

func Printable(a string) string

Printable returns all printable runes of string a as defined by Go. All non-printable runes of string a are dropped.

func ReadFile 

func ReadFile(f Filename) ([]byte, error)

ReadFile reads f and and returns it contents. It returns an error, if any. If a file does not exist, it returns an error. If successful, error will be nil.

func RemoveFile 

func RemoveFile(f Filename) error

RemoveFile removes file f. It returns an error, if there is any. If f is a directory it returns an error. If f does not exist, it also returns an error.

func ResetFile 

func ResetFile(fn Filename) error

ResetFile truncates fn to size zero. If fn does not exist, it is created as empty file. It returns an error, if there is any.

func RuneToPrintable added in v1.3.0 

func RuneToPrintable(r rune) string

RuneToPrintable returns rune r as a string, if it is printable. Otherwise, it returns an empty string.

func Sprintf 

func Sprintf[T Fio](f string, a ...any) T

Sprintf formats according to the format specifier and returns the resulting Filename or Directory

func TouchFile 

func TouchFile(fn Filename) error

TouchFile updates the access and modification times of filename fn to the current time. If fn does not exist, it is created as an empty file. It returns an error, if any.

func WriteSingleStr 

func WriteSingleStr(fn Filename, s string) error

WriteSingleStr writes a single string s to file fn. If fn exists, it is truncated to size zero first. If it does not exist, it is created. It returns an error, if any.

func WriteStr 

func WriteStr(fn Filename, s string) error

WriteStr writes string s to file with filename fn. It returns an error, if any. If fn exists already, the string will be appended to the file. If fn does not exist, it will create fn.

Types

type Append 

type Append struct {
	FileA Filename // fileA to be extended
	FileI Filename // fileI holds the contents to be appended to fileA
}

Append holds filename fileA, the file to be extended by contents from file I, and filename fileI, which is the input file and will be appended to fileA.

type Directory 

type Directory string

A Directory is the name of a directory and may contain its path

func InvalDir added in v1.3.0 

func InvalDir() [4]Directory

InvalDir returns the array of blocked directories. If a directory or their parents match InvalDir, tsfio functions will return an error.

type Filename 

type Filename string

A Filename is the name of a regular file and may contain its path

func GoldenFilePath added in v1.3.0 

func GoldenFilePath(name string) (Filename, error)

GoldenFilePath returns the path of the test data golden file for the provided name of a testcase. The golden files are stored in the default golden files directory testdata/ and have the default golden file type .golden.

func InvalFile added in v1.3.0 

func InvalFile() [14]Filename

InvalFile returns the array of blocked filenames. If a Filename matches InvalFile, tsfio functions will return an error.

func Path added in v1.3.0 

func Path(d Directory, f Filename) (Filename, error)

Path joins directory name d and a filename f into a single path p. It returns an empty string and an error if checks on d, f and p fail. Path joins the path elements by using the Join function from the Go standard library package path/filepath.

type Fio added in v1.3.0 

type Fio interface {
	Filename | Directory
}

Interface Fio is constrained to type Filename and Directory

type Testcase added in v1.3.0 

type Testcase struct {
	Name string // Name of the testcase
	Data string // Data of the testcase
}

A Testcase contains the name of a testcase and the corresponding data of the testcase. The data can be reference data or test data.

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.