fsmodtime

README

= fsmodtime

image:https://pkg.go.dev/badge/github.com/DavidGamba/dgtools/fsmodtime.svg[Go Reference, link="https://pkg.go.dev/github.com/DavidGamba/dgtools/fsmodtime"] link:fsmodtime[] - Provides functions to determine if you want to build targets from sources based on modification time.

== Example

Build a binary if any of the source files have been modified or if the binary does not yet exist.

[source,go]
----
import (
	"github.com/DavidGamba/dgtools/fsmodtime"
	"github.com/DavidGamba/dgtools/run"
)

		files, modified, err := fsmodtime.Target(os.DirFS("."), []string{"binary_name"}, []string{"go.mod", "go.sum", "*.go"})
		if err != nil {
			return fmt.Errorf("failed to detect changes: %w", err)
		}
		if !modified {
			return nil
		}
		Logger.Printf("Modified files: %v\n", files)

		err = run.CMD("go", "build", "-o", "binary_name").Log().Run()
		if err != nil {
			return fmt.Errorf("failed to build go project: %w", err)
		}
----

Documentation

Overview

package fsmodtime provides functions to compare fs mod times.

The goal of this package is to have functions that allow me to determine if my sources (fs dependencies) have been modified (changed) so that based on that I can rebuild my targets.

Additionally I want to log the file (not necessarily all of them but at least one) that changed for informational/verification purposes when building build systems downstream.

The function that meets that goal is Target.

Requirements:

• Targets might not exist yet. In that case, build them.
• All declared targets must exist. Rebuild otherwise.
• Not all sources are required to exist. For example, I might want a blank *.jpg and *.png in my build system but some image types might not exist.
• ExpandEnv but don't fail silently if my Env Var expansions fail.
• Allow for globs.

Example:

targets := []string{"$outputs_dir/doc.pdf", "$outputs_dir/*.html"}
sources := []string{"$src_dir/*.adoc", "$images_dir/*.jpg", "$images_dir/*.png"}
paths, modified, err := Target(os.DirFS("."), targets, sources)

Index

• Variables
• func ExpandEnv(lines []string) ([]string, error)
• func First(fsys fs.FS, paths []string, opts ...WalkOpt) (filepath string, fileInfo fs.FileInfo, err error)
• func Glob(fsys fs.FS, stop bool, patterns []string) (matches []string, stopped bool, err error)
• func Last(fsys fs.FS, paths []string, opts ...WalkOpt) (filepath string, fileInfo fs.FileInfo, err error)
• func ParentDir(paths []string) (string, error)
• func Target(fsys fs.FS, targets []string, sources []string, opts ...WalkOpt) ([]string, bool, error)
• func TargetTime(fsys fs.FS, targetTime time.Time, sources []string, opts ...WalkOpt) ([]string, bool, error)
• type WalkOpt
  • func Recursive(enabled bool) WalkOpt
• type WalkOpts

Variables

var (
	ErrInvalidPath = fmt.Errorf("invalid path")
	ErrInvalidFS   = fmt.Errorf("invalid fs")
	ErrNotFound    = fmt.Errorf("not found")
)

var Logger = log.New(io.Discard, "", log.LstdFlags)

Functions

func ExpandEnv

func ExpandEnv(lines []string) ([]string, error)

ExpandEnv - like os.ExpandEnv on many lines, except that it reports error if any of the env vars is not found. It also expands ~/ to $HOME/

func First

func First(fsys fs.FS, paths []string, opts ...WalkOpt) (filepath string, fileInfo fs.FileInfo, err error)

First - given a list of paths, it finds the file with the earliest modTime and returns it.

root := "."
fileSystem := os.DirFS(root)
path, fi, err := fsmodtime.First(fileSystem, paths, fsmodtime.Recursive(true))

Use fsmodtime.Recursive(true) to recurse into directories.

func Glob

func Glob(fsys fs.FS, stop bool, patterns []string) (matches []string, stopped bool, err error)

Glob - like io/fs.Glob on many paths. It allows to stop globbing patterns once it has found a pattern that has no matches. Glob syntax described here: https://golang.org/pkg/path/filepath/#Match

Returns the list of matches, a bool indicating if there is a pattern that had no matches and an error

func Last

func Last(fsys fs.FS, paths []string, opts ...WalkOpt) (filepath string, fileInfo fs.FileInfo, err error)

Last - given a list of paths, it finds the file with the latest modTime and returns it.

root := "."
fileSystem := os.DirFS(root)
path, fi, err := fsmodtime.Last(fileSystem, paths, fsmodtime.Recursive(true))

Use fsmodtime.Recursive(true) to recurse into directories.

func ParentDir

func ParentDir(paths []string) (string, error)

ParentDir - Given a list of paths, it finds the common parent dir. Assumes / as the filepath separator.

func Target

func Target(fsys fs.FS, targets []string, sources []string, opts ...WalkOpt) ([]string, bool, error)

Target - Given a list of targets it indicates whether or not the sources have modifications past the targets last. The first return is the file modified.

Use fsmodtime.Recursive(true) to recurse into directories.

func TargetTime

func TargetTime(fsys fs.FS, targetTime time.Time, sources []string, opts ...WalkOpt) ([]string, bool, error)

TargetTime - Given a time it indicates whether or not the sources have modifications past the time. The first return is the file modified.

Use fsmodtime.Recursive(true) to recurse into directories.

Types

type WalkOpt

type WalkOpt func(*WalkOpts)

func Recursive

func Recursive(enabled bool) WalkOpt

type WalkOpts

type WalkOpts struct {
	// contains filtered or unexported fields
}