Documentation
¶
Overview ¶
Package file provides context-aware file operations that integrate with the ReaderIOResult monad. It offers safe, composable file I/O operations that respect context cancellation and properly manage resources using the RAII pattern.
All operations in this package:
- Respect context.Context for cancellation and timeouts
- Return ReaderIOResult for composable error handling
- Automatically manage resource cleanup
- Are safe to use in concurrent environments
Example Usage ¶
// Read a file with automatic resource management
readOp := ReadFile("data.txt")
result := readOp(ctx)()
// Open and manually manage a file
fileOp := Open("config.json")
fileResult := fileOp(ctx)()
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Open opens a file for reading within the given context. // The operation respects context cancellation and returns a ReaderIOResult // that produces an os.File handle on success. // // The returned file handle should be closed using the Close function when no longer needed, // or managed automatically using WithResource or ReadFile. // // Parameters: // - path: The path to the file to open // // Returns: // - ReaderIOResult[*os.File]: A context-aware computation that opens the file // // Example: // // openFile := Open("data.txt") // result := openFile(ctx)() // either.Fold( // result, // func(err error) { log.Printf("Error: %v", err) }, // func(f *os.File) { // defer f.Close() // // Use file... // }, // ) // // See Also: // - ReadFile: For reading entire file contents with automatic resource management // - Close: For closing file handles Open = F.Flow3( IOEF.Open, RIOE.FromIOEither[*os.File], RIOE.WithContext[*os.File], ) // Remove removes a file by name. // The operation returns the filename on success, allowing for easy composition // with other file operations. // // Parameters: // - name: The path to the file to remove // // Returns: // - ReaderIOResult[string]: A computation that removes the file and returns its name // // Example: // // removeOp := Remove("temp.txt") // result := removeOp(ctx)() // either.Fold( // result, // func(err error) { log.Printf("Failed to remove: %v", err) }, // func(name string) { log.Printf("Removed: %s", name) }, // ) // // See Also: // - Open: For opening files // - ReadFile: For reading file contents Remove = F.Flow2( IOEF.Remove, RIOE.FromIOEither[string], ) )
Functions ¶
This section is empty.
Types ¶
type Kleisli ¶ added in v2.2.21
type Kleisli[A, B any] = readerioresult.Kleisli[A, B]
Kleisli represents a Kleisli arrow for ReaderIOResult. It is a function that takes a value of type A and returns a ReaderIOResult[B].
Kleisli arrows are used for monadic composition, allowing you to chain operations that produce ReaderIOResults. They are particularly useful with Chain and Bind operations.
Kleisli[A, B] is equivalent to:
func(A) ReaderIOResult[B]
Example:
// A Kleisli arrow that reads a file given its path var readFileK Kleisli[string, []byte] = ReadFile
See Also:
- readerioresult.Kleisli: The underlying type definition
- Operator: For transforming ReaderIOResults
func Write ¶
func Write[R any, W io.WriteCloser](acquire ReaderIOResult[W]) Kleisli[Kleisli[W, R], R]
Write uses a generator function to create a stream, writes data to it and closes it
type Operator ¶ added in v2.2.21
type Operator[A, B any] = readerioresult.Operator[A, B]
Operator represents a transformation from one ReaderIOResult to another. This is useful for point-free style composition and building reusable transformations.
Operator[A, B] is equivalent to:
func(ReaderIOResult[A]) ReaderIOResult[B]
Operators are used to transform computations without executing them, enabling powerful composition patterns.
Example:
// An operator that maps over file contents
var toUpper Operator[[]byte, string] = Map(func(data []byte) string {
return strings.ToUpper(string(data))
})
See Also:
- readerioresult.Operator: The underlying type definition
- Kleisli: For functions that produce ReaderIOResults
type ReaderIOResult ¶ added in v2.2.21
type ReaderIOResult[A any] = readerioresult.ReaderIOResult[A]
ReaderIOResult represents a context-aware computation that performs side effects and can fail with an error. This is the main type used throughout the file package for all file operations.
ReaderIOResult[A] is equivalent to:
func(context.Context) func() Either[error, A]
The computation:
- Takes a context.Context for cancellation and timeouts
- Performs side effects (IO operations)
- Returns Either an error or a value of type A
See Also:
- readerioresult.ReaderIOResult: The underlying type definition
func Close ¶
func Close[C io.Closer](c C) ReaderIOResult[Void]
Close closes an io.Closer resource and returns a ReaderIOResult. This function is generic and works with any type that implements io.Closer, including os.File, network connections, and other closeable resources.
The function captures any error that occurs during closing and returns it as part of the ReaderIOResult. On success, it returns Void (empty struct).
Type Parameters:
- C: Any type that implements io.Closer
Parameters:
- c: The resource to close
Returns:
- ReaderIOResult[Void]: A computation that closes the resource
Example:
file, _ := os.Open("data.txt")
closeOp := Close(file)
result := closeOp(ctx)()
Note: This function is typically used with WithResource for automatic resource management rather than being called directly.
See Also:
- Open: For opening files
- ReadFile: For reading files with automatic closing
func CreateTemp ¶
func CreateTemp(dir, pattern string) ReaderIOResult[*os.File]
CreateTemp created a temp file with proper parametrization
func ReadFile ¶
func ReadFile(path string) ReaderIOResult[[]byte]
ReadFile reads the entire contents of a file in a context-aware manner. This function automatically manages the file resource using the RAII pattern, ensuring the file is properly closed even if an error occurs or the context is canceled.
The operation:
- Opens the file for reading
- Reads all contents into a byte slice
- Automatically closes the file when done
- Respects context cancellation during the read operation
Parameters:
- path: The path to the file to read
Returns:
- ReaderIOResult[[]byte]: A computation that reads the file contents
Example:
readOp := ReadFile("config.json")
result := readOp(ctx)()
either.Fold(
result,
func(err error) { log.Printf("Read error: %v", err) },
func(data []byte) { log.Printf("Read %d bytes", len(data)) },
)
The function uses WithResource internally to ensure proper cleanup:
ReadFile(path) = WithResource(Open(path), Close)(readAllBytes)
See Also:
- Open: For opening files without automatic reading
- Close: For closing file handles
- WithResource: For custom resource management patterns
Example ¶
package main
import (
"context"
"fmt"
R "github.com/IBM/fp-go/v2/context/readerioresult"
F "github.com/IBM/fp-go/v2/function"
"github.com/IBM/fp-go/v2/io"
J "github.com/IBM/fp-go/v2/json"
)
type RecordType struct {
Data string `json:"data"`
}
func getData(r RecordType) string {
return r.Data
}
func main() {
data := F.Pipe3(
ReadFile("./data/file.json"),
R.ChainEitherK(J.Unmarshal[RecordType]),
R.ChainFirstIOK(io.Logf[RecordType]("Log: %v")),
R.Map(getData),
)
result := data(context.Background())
fmt.Println(result())
}
Output: Right[string](Carsten)
func WithTempFile ¶
func WithTempFile[A any](f Kleisli[*os.File, A]) ReaderIOResult[A]
WithTempFile creates a temporary file, then invokes a callback to create a resource based on the file, then close and remove the temp file
type Void ¶ added in v2.2.21
Void represents the absence of a meaningful value, similar to unit type in other languages. It is used when a function performs side effects but doesn't return a meaningful result.
Void is typically used as the success type in operations like Close that perform an action but don't produce a useful value.
Example:
Close[*os.File](file) // Returns ReaderIOResult[Void]
See Also:
- function.Void: The underlying type definition
Source Files