walk

README

About

go-fs-walk provides a Cursor that recursively walks through filesystems (including archive files like zip and tgz). Filters can be used to control visited files and folders.

If you need to easily access files inside zips that are inside three layers of tars, this is the package for you.

Installing

Using Go Modules:

go get github.com/korylprince/go-fs-walk

If you have any issues or questions create an issue.

Usage

See example on pkg.go.dev.

To Do

• Add more archive formats (Send a PR!)
• Add test data
• Add safety for untrusted inputs (see below)

Safety

Cursor is neither thread-safe, nor should it be used on untrusted data.

Documentation

Overview

package walk recursively walks through filesystems (including archive files like zip and tgz). Filters can be used to control visited files and folders.

Example (CursorWalk)

package main

import (
	"fmt"
	"io"
	"io/fs"
	"path/filepath"
	"strings"

	walk "github.com/korylprince/go-fs-walk"
)

func UnluckyFilter(fi fs.FileInfo, path string, err error) error {
	//skip files and folders named 13
	if strings.TrimSuffix(fi.Name(), filepath.Ext(fi.Name())) == "13" {
		return walk.SkipRecurse
	}
	return nil
}

func main() {
	c := walk.New("/path/to/root")
	c.RegisterFilterFunc("unlucky", UnluckyFilter)
	for fi, path, err := c.Next(); err != io.EOF; fi, path, err = c.Next() {
		if err != nil {
			panic(err)
		}
		fmt.Printf("Found lucky file %s at %s", fi.Name(), path)
		//use c as io.Reader...
	}
}

Index

• Variables
• type Cursor
  • func New(path string) *Cursor
  • func (c *Cursor) Close()
  • func (c *Cursor) Next() (fi fs.FileInfo, path string, err error)
  • func (c *Cursor) Read(b []byte) (int, error)
  • func (c *Cursor) RegisterFilterFunc(name string, fn CursorFilterFunc)
  • func (c *Cursor) UnregisterFilterFunc(name string)
• type CursorFilterFunc

Examples

• Package (CursorWalk)

Variables

var Skip = errors.New("Skip")

var SkipRecurse = errors.New("SkipRecurse")

Types

type Cursor

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

func New

func New(path string) *Cursor

New returns a new Cursor for the given path (directory or file). The Cursor is not thread-safe, and should not be used on untrusted data

func (*Cursor) Close

func (c *Cursor) Close()

Close can be used to close the cursor prematurely. The cursor is closed implicitly when Next returns io.EOF

func (*Cursor) Next

func (c *Cursor) Next() (fi fs.FileInfo, path string, err error)

Next moves the Cursor to the next file or directory and returns the fs.FileInfo, full path, and an error if one occurred. Next returns io.EOF after the last file or directory has been read and the Cursor is closed.

func (*Cursor) Read

func (c *Cursor) Read(b []byte) (int, error)

Read implements io.Reader. Read should not be called if the last call to Next returns a directory or an error. If Next returns io.EOF, Read should not be called again.

func (*Cursor) RegisterFilterFunc

func (c *Cursor) RegisterFilterFunc(name string, fn CursorFilterFunc)

RegisterFilterFunc registers the given CursorFilterFunc for the Cursor. Filters are processed in the order they are registered

func (*Cursor) UnregisterFilterFunc

func (c *Cursor) UnregisterFilterFunc(name string)

UnregisterFilterFunc unregisters the given CursorFilterFunc

type CursorFilterFunc

type CursorFilterFunc func(fi fs.FileInfo, path string, err error) error

CursorFilterFunc receives the fs.FileInfo, path, and error before it is returned by Next. If the error returned is nil, then the Cursor returns the file as normal. If Skip is returned, the Cursor will move to the next file, including inside the current directory or archive file. If SkipRecurse is returned, and the cursor is at a directory or archive file, the directory or archive file will be returned, but won't be recursed into. If any other error is returned, Next will receive io.EOF and the Cursor will be closed