filewriter

README

filewriter - file writer that does not keep open file handles

filewriter is a package for writing things to files that other processes may also be writing to at the same time so it does not keep any open file handles longer than absolutely necessary.

Installation

> go get github.com/go-corelibs/filewriter@latest

Examples

Write, WalkFile, Remove

func main() {
    // create a new writer using defaults and a temp file
    var err error
    var fw filewriter.FileWriter
    if fw, err = filewriter.New().Make(); err != nil {
        panic(err)
    }
    defer fw.Remove() // cleanup the file when we're done
    // write things to the file
    if err = fw.Write([]byte("two lines\nof text")); err != nil {
        panic(err)
    }
    // need to read the file? fw.ReadFile gives the whole contents,
    // however for large files perhaps the WalkFile is better!
    stopped := fw.WalkFile(func(line string) (stop bool) {
        // do something with this line of file contents and
        // to stop the walking process, return true, otherwise
        // the walk continues to the end of the file
        return
    })
    // stopped == false because the func did not return true
}

Go-CoreLibs

Go-CoreLibs is a repository of shared code between the Go-Curses and Go-Enjin projects.

License

Copyright 2023 The Go-CoreLibs Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use file except in compliance with the License.
You may obtain a copy of the license at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

Index

• Variables
• type Builder
  • func New() Builder
• type FileWriter

Variables

var (
	// DefaultFileMode is the file mode used by NewFileWriter
	DefaultFileMode os.FileMode = 0644
	// DefaultOpenFlag is the os.OpenFile flag used by NewFileWriter
	DefaultOpenFlag = os.O_CREATE | os.O_WRONLY | os.O_APPEND
	// DefaultTempFile is the os.CreateTemp pattern used by NewFileWriter
	DefaultTempFile = "filewriter-*.tmp"
)

Types

type Builder

type Builder interface {
	// SetFile specifies the file path to use
	SetFile(file string) Builder
	// UseTemp specifies the pattern to use with os.CreateTemp. If the pattern
	// includes a unix directory separator, the `pattern` argument is the base
	// name and the rest is used as the `dir` argument
	UseTemp(pattern string) Builder
	// SetMode specifies the file permissions to use when creating files
	SetMode(mode os.FileMode) Builder
	// Make initializes the settings configured with other Builder methods and
	// returns the FileWriter instance
	Make() (writer FileWriter, err error)
}

Builder is the buildable interface for constructing new FileWriter instances

func New

func New() Builder

New constructs a new Builder instance with the DefaultOpenFlag and DefaultFileMode

type FileWriter

type FileWriter interface {
	// File returns the underlying file name
	File() (file string)
	// Mode returns the file permissions used when creating files
	Mode() (mode os.FileMode)
	// Remove deletes the underlying file
	Remove() (err error)

	// Write opens the log file, writes the data given and returns the number
	// of bytes written and the error state after closing the open file handle
	Write(p []byte) (n int, err error)
	// WriteString is a convenience wrapper around Write
	WriteString(s string) (n int, err error)
	// Close flags this FileWriter as being closed, blocking any further Write
	// or WriteString operations; ReadFile and WalkFile can still be used
	// until Remove is called
	Close() (err error)

	// ReadFile returns the entire file contents
	ReadFile() (data []byte, err error)
	// WalkFile opens the output file and scans one line at a time, calling the
	// given `fn` for each. If the `fn` returns true, the walk stops. WalkFile
	// returns true if the walk was stopped. WalkFile will panic on any os.Open
	// error that is not os.ErrNotExist
	WalkFile(fn func(line string) (stop bool)) (stopped bool)
}

FileWriter is an io.WriteCloser that does not keep file handles open any longer than necessary and provides additional methods for interacting with the underlying file. All operations are safe for concurrent calls