objectify

README

Objectify

Objectify is a Go package that reads a directory's entries and returns a slice of structs which contain information about each directory entry like size, file mode, the symlink target, and checksums.

Import this Module

go get github.com/orme292/objectify@latest

import (
    objf "github.com/orme292/objectify"
)

Usage

Objectify can be called by passing a path and a Sets struct.

Sets

The Sets struct tells Objectify which fields should be populated for each directory entry.

func main() {

setter := objf.Sets{
        Size: true,
        Modes: true,
        ChecksumMD5: true,
        ChecksumSHA256: true,
        LinkTarget: true,
        LinkTargetFinal: true,
    }

}

You can also have a Sets object returned by using a builder function:

• setter := SetsAll() All fields will be populated.
• setter := SetsAllNoChecksums() All fields except ChecksumSHA256/ChecksumMD5 will be populated.
• setter := SetsAllMD5() All fields except ChecksumSHA256 will be populated.
• setter := SetsAllSHA256() All fields except ChecksumMD5 will be populated
• setter := SetsNone() No optional fields will be populated.

Call Objectify

You can call objectify by using the Path() or File() functions.

Path() will walk a directory and return a Files slice and an error, if there is one:

files, err := objf.Path("/root/path", objf.SetsAll())

File() will process a single file and return a FileObj struct and an error, if there is one:

file, err := objf.File("/root/path/myfile.txt", objf.SetsNone())

Create your own Sets for more configuration:

setter := objf.Sets{
    Size: true,
    Modes: true,
    LinkTarget: true,
    LinkTargetFinal: true,
}
files, err := objf.Path("/root/path", setter)

The Files & FileObj Types

Path() returns a Files slice. The Files slice is made of FileObj structs. File() returns a FileObj struct.

type Files []*FileObj

type FileObj struct {
    UpdatedAt time.Time

    Filename string
    Root     string

    SizeBytes int64

    ChecksumMD5    string
    MD5            []byte
    ChecksumSHA256 string
    SHA256         []byte

    Mode   entMode
    info   fs.FileMode

    Target      string
    TargetFinal string

    IsLink     bool
    IsReadable bool
    IsExists   bool

    Sets *Sets
}

FileObj methods

• FileObj.ChangeSets() updates the Sets, but does not trigger an update.
• FileObj.Force() Forces an update on an optional field, despite Sets values.
• FileObj.FullPath() returns a string that joins the root directory with the entry's filename.
• FileObj.HasChanged() returns true if the file has changed since the struct was last populated.
• FileObj.SecondsSinceUpdatedAt() returns the number of seconds elapsed since the FileObj's fields were updated.
• FileObj.SizeString() returns a human-readable string representation of the directory entry's size (i.e. 500 MB)
• FileObj.Update() updates all fields if the actual file has been modified since the fields were originally populated.

Example

Here's an example of basic Objectify usage:

package main

import (
    "fmt"
    "os"
    
    objf "github.com/orme292/objectify"
)

func main() {

    files, err := objf.Path("/root/dir", objf.SetsAll())
    if err != nil {
        fmt.Printf("Error occurred: %s", err.Error())
        os.Exit(1)
    }
    
    for _, entry := range files {
        fmt.Printf("%s is %d BYTES", entry.FullPath(), entry.SizeBytes)
    }
    
    os.Exit(0)
}

Documentation

Overview

Package objectify reads a provided directory and turns each directory entry / file into an object. Each object (FileObj) contains calculated checksums, symlink target paths, size and file mode information, and provides functions to check for recent modifications.

Index

• Constants
• type Action
• type FileObj
  • func File(path string, s Sets) (file *FileObj, err error)
  • func (fo *FileObj) ChangeSets(s Sets)
  • func (fo *FileObj) DebugOut()
  • func (fo *FileObj) Force(a Action)
  • func (fo *FileObj) FullPath() string
  • func (fo *FileObj) HasChanged() bool
  • func (fo *FileObj) SecondsSinceUpdatedAt() int64
  • func (fo *FileObj) SizeString() string
  • func (fo *FileObj) Update() *FileObj
• type Files
  • func Path(rootPath string, s Sets) (files Files, err error)
• type Sets
  • func SetsAll() Sets
  • func SetsAllMD5() Sets
  • func SetsAllNoChecksums() Sets
  • func SetsAllSHA256() Sets
  • func SetsNone() Sets

Constants

const (
	EMPTY = ""
)

Types

type Action

type Action int

const (
	F_CHECKSUM_MD5 Action = iota
	F_CHECKSUM_SHA256
	F_MODES
	F_SIZE
	F_LINKTARGET
)

type FileObj

type FileObj struct {

	// UpdatedAt represents the last time this struct was updated.
	UpdatedAt time.Time

	// Filename is the base name of the directory entry.
	// Root is the parent directory.
	Filename string
	Root     string

	// SizeBytes is the size of the file in Bytes.
	SizeBytes int64

	// ChecksumMD5 and ChecksumSHA256 are hash byte array string-representations.
	// MD5 and SHA256 are the hash byte arrays.
	ChecksumMD5    string
	MD5            []byte
	ChecksumSHA256 string
	SHA256         []byte

	// Mode is the entMode of the directory entry.
	// modeFS is returned from os.Lstat
	Mode entMode

	// Target will be populated with a symlinks target path.
	Target      string
	TargetFinal string

	IsLink     bool
	IsReadable bool
	IsExists   bool

	Set *Sets
	// contains filtered or unexported fields
}

FileObj represents a directory entry object.

func File

func File(path string, s Sets) (file *FileObj, err error)

File is a function that accepts a path and a Sets struct as parameters. It creates a worker instance and runs it using the run function to collect file information. It returns a slice of FileObj structs and an error if any. The returned slice should contain a single FileObj, if not, nil and an error is returned. As long as the files slice contains a single FileObj, it is returned.

func (*FileObj) ChangeSets

func (fo *FileObj) ChangeSets(s Sets)

ChangeSets overwrites the Set field with a new Sets object.

func (*FileObj) DebugOut

func (fo *FileObj) DebugOut()

func (*FileObj) Force

func (fo *FileObj) Force(a Action)

Force applies the specified action to the FileObj by changing its sets and calling the corresponding helper methods. The original sets of the FileObj are stored temporarily and restored after applying the action. The available actions are:

• F_CHECKSUM_MD5: Changes the sets to enable checksum MD5 calculation and calls the setChecksums() method.
• F_CHECKSUM_SHA256: Changes the sets to enable checksum SHA256 calculation and calls the setChecksums() method.
• F_MODES: Changes the sets to enable mode and file info retrieval and calls the setEntMode() method.
• F_SIZE: Changes the sets to enable size calculation and calls the setSize() method.
• F_LINKTARGET: Changes the sets to enable link target retrieval and calls the setTargets() method.

func (*FileObj) FullPath

func (fo *FileObj) FullPath() string

FullPath returns the full path of the FileObj by joining the Root and Filename. Utilizes filepath.Join to combine the two components.

func (*FileObj) HasChanged

func (fo *FileObj) HasChanged() bool

HasChanged checks if the file specified by FileObj has been modified since its last update. It returns true if the file exists, is readable, and its modification time is after the last update time. Otherwise, it returns false.

func (*FileObj) SecondsSinceUpdatedAt

func (fo *FileObj) SecondsSinceUpdatedAt() int64

SecondsSinceUpdatedAt returns the number of seconds since the UpdatedAt time of the FileObj.

func (*FileObj) SizeString

func (fo *FileObj) SizeString() string

SizeString returns the formatted string representation of the size in bytes. Converts the given size in bytes to a human-readable format (e.g., KB, MB, GB, etc.).

func (*FileObj) Update

func (fo *FileObj) Update() *FileObj

Update checks if the file specified by FileObj has been modified since its last update. If it has changed, and the file exists, is readable, and its modification time is after the last update time, Update calls update.

type Files

type Files []*FileObj

func Path

func Path(rootPath string, s Sets) (files Files, err error)

Path is a function that takes a rootPath and a Sets struct as parameters. It creates a worker instance and runs it using the run function to collect file information. It returns a slice of FileObj structs and an error if any. The Sets struct is used to specify which fields of the FileObj struct need to be populated.

type Sets

type Sets struct {
	Size            bool
	Modes           bool
	ChecksumMD5     bool
	ChecksumSHA256  bool
	LinkTarget      bool
	LinkTargetFinal bool
}

Sets fields are flags for FileObj fields which can be optionally populated.

func SetsAll

func SetsAll() Sets

SetsAll returns a Sets object with all fields set to true.

func SetsAllMD5

func SetsAllMD5() Sets

SetsAllMD5 returns a Sets object with all fields set to true, except for ChecksumSHA256.

func SetsAllNoChecksums

func SetsAllNoChecksums() Sets

SetsAllNoChecksums sets all fields of the Sets object to true, except for the ChecksumMD5 and ChecksumSHA256.

func SetsAllSHA256

func SetsAllSHA256() Sets

SetsAllSHA256 returns a Sets object with all fields set to true, except for ChecksumMD5.

func SetsNone

func SetsNone() Sets

SetsNone returns a Sets object with all fields set to false.