drydock

README

DryDock

Simple Scaffolding Library for Go

Usage Example

g := &FSGenerator{
	FS: NewWritableDirFS("out"),
}

err := g.Generate(
    context.Background(),
	PlainFile("README.md", "# drydock"),
	Dir("bin",
		Dir("cli",
			PlainFile("main.go", "package main"),
		),
	),
	Dir("pkg",
		PlainFile("README.md", "how to use this thing"),
		Dir("cli",
			PlainFile("cli.go", "package cli..."),
			PlainFile("run.go", "package cli...run..."),
		),
	),
)

License

MIT

Documentation

Index

• Variables
• func Render(files ...File) string
• type DirFSGenerator
  • func (g *DirFSGenerator) Generate(ctx context.Context, files ...File) error
• type Directory
  • func Dir(name string, entries ...File) Directory
  • func DirP(name string, entries ...File) Directory
• type FSGenerator
  • func (g *FSGenerator) Generate(ctx context.Context, files ...File) error
• type File
  • func FileFromTemplate(name string, template Template, data any) File
  • func ModifyFile[E any](name string, parse func([]byte, any) error, mod func(*E) ([]byte, error)) File
  • func PlainFile(name string, contents string) File
  • func TemplateFile(name string, template string, data any) File
• type IsNewFile
• type Template
• type WritableFS
  • func MkWritableDirFS(dir string) (WritableFS, error)
  • func MkpWritableDirFS(dir string) (WritableFS, error)
  • func NewWritableDirFS(dir string) WritableFS
• type WritableFile
• type WritableMapFS
  • func (fsys WritableMapFS) CreateTemp(dir string, pattern string) (WritableFile, error)
  • func (fsys WritableMapFS) Glob(pattern string) ([]string, error)
  • func (fsys WritableMapFS) Mkdir(name string, perm fs.FileMode) error
  • func (fsys WritableMapFS) Open(name string) (fs.File, error)
  • func (fsys WritableMapFS) ReadDir(name string) ([]fs.DirEntry, error)
  • func (fsys WritableMapFS) ReadFile(name string) ([]byte, error)
  • func (fsys WritableMapFS) Remove(path string) error
  • func (fsys WritableMapFS) RemoveAll(dir string) error
  • func (fsys WritableMapFS) Rename(oldpath string, newpath string) error
  • func (fsys WritableMapFS) Stat(name string) (fs.FileInfo, error)
  • func (fsys WritableMapFS) Sub(dir string) (fs.FS, error)
• type WriterToFile

Examples

• FSGenerator.Generate

Variables

var ErrCleaningOutputDir = errors.New("error cleaning output dir")

var ErrMissingFS = errors.New("missing FS")

Functions

func Render

func Render(files ...File) string

Types

type DirFSGenerator

type DirFSGenerator struct {
	OutputDir           string
	ErrorOnExistingDir  bool
	NoCreateOutputDir   bool
	CleanDir            bool
	ErrorOnExistingFile bool
}

func (*DirFSGenerator) Generate

func (g *DirFSGenerator) Generate(ctx context.Context, files ...File) error

type Directory

type Directory interface {
	File
	Entries() ([]File, error)
}

func Dir

func Dir(name string, entries ...File) Directory

func DirP

func DirP(name string, entries ...File) Directory

DirP is like Dir but [name] can be a file path and every segment will be created as a directory, similar to os.MkdirAll or the `mkdir -p` command.

type FSGenerator

type FSGenerator struct {
	FS WritableFS

	ErrorOnExistingDir  bool
	CleanDir            bool
	ErrorOnExistingFile bool
	// contains filtered or unexported fields
}

func (*FSGenerator) Generate

func (g *FSGenerator) Generate(ctx context.Context, files ...File) error

Example

outpath := path.Join(os.TempDir(), "out")
outfs, err := MkWritableDirFS(outpath)
if err != nil {
	panic(err)
}

g := &FSGenerator{
	FS: outfs,
}

err = g.Generate(
	context.Background(),
	PlainFile("README.md", "# drydock"),
	Dir("bin",
		Dir("cli",
			PlainFile("main.go", "package main"),
		),
	),
	Dir("pkg",
		PlainFile("README.md", "how to use this thing"),
		Dir("cli",
			PlainFile("cli.go", "package cli..."),
			PlainFile("run.go", "package cli...run..."),
		),
	),
)

if err != nil {
	panic(err)
}

entries, err := os.ReadDir(outpath)
if err != nil {
	panic(err)
}

for _, e := range entries {
	fmt.Println(e)
}

Output:

- README.md
d bin/
d pkg/

type File

type File interface {
	Name() string
}

func FileFromTemplate

func FileFromTemplate(name string, template Template, data any) File

func ModifyFile

func ModifyFile[E any](name string, parse func([]byte, any) error, mod func(*E) ([]byte, error)) File

func PlainFile

func PlainFile(name string, contents string) File

func TemplateFile

func TemplateFile(name string, template string, data any) File

type IsNewFile

type IsNewFile interface {
	IsNewFile() bool
}

type Template

type Template interface {
	Execute(w io.Writer, data any) error
}

type WritableFS

type WritableFS interface {
	fs.ReadFileFS

	// Mkdir should behave like [os.Mkdir].
	Mkdir(name string, perm fs.FileMode) error

	// Rename should behave like [os.Rename]. Returned errors will also be [os.LinkError].
	Rename(oldpath string, newpath string) error

	// Remove should behave like [os.Remove].
	Remove(path string) error

	// RemoveAll should behave like [os.RemoveAll].
	RemoveAll(path string) error

	// CreateTemp should behave like [os.CreateTemp].
	CreateTemp(dir string, pattern string) (WritableFile, error)
}

WritableFS extends the standard io/fs.FS interface with writing capabilities for hierarchical file systems.

func MkWritableDirFS

func MkWritableDirFS(dir string) (WritableFS, error)

MkWritableDirFS is like NewWritableDirFS but will create the directory if it doesn't exist.

func MkpWritableDirFS

func MkpWritableDirFS(dir string) (WritableFS, error)

MkpWritableDirFS is like MkWritableDirFS but will create the directory and any parent directory if it doesn't exist.

func NewWritableDirFS

func NewWritableDirFS(dir string) WritableFS

NewWritableDirFS creates a new [WritablesFS] backed by the real filesystem, like os.DirFS.

type WritableFile

type WritableFile interface {
	fs.File
	io.Writer
	Name() string
}

type WritableMapFS

type WritableMapFS fstest.MapFS

WritableMapFS extends testing/fstest.MapFS with WritableFS capabilities.

func (WritableMapFS) CreateTemp

func (fsys WritableMapFS) CreateTemp(dir string, pattern string) (WritableFile, error)

CreateTemp does not implement the pattern function of os.CreateTemp. The default temp dir is `/tmp`.

func (WritableMapFS) Glob

func (fsys WritableMapFS) Glob(pattern string) ([]string, error)

func (WritableMapFS) Mkdir

func (fsys WritableMapFS) Mkdir(name string, perm fs.FileMode) error

func (WritableMapFS) Open

func (fsys WritableMapFS) Open(name string) (fs.File, error)

func (WritableMapFS) ReadDir

func (fsys WritableMapFS) ReadDir(name string) ([]fs.DirEntry, error)

func (WritableMapFS) ReadFile

func (fsys WritableMapFS) ReadFile(name string) ([]byte, error)

func (WritableMapFS) Remove

func (fsys WritableMapFS) Remove(path string) error

func (WritableMapFS) RemoveAll

func (fsys WritableMapFS) RemoveAll(dir string) error

func (WritableMapFS) Rename

func (fsys WritableMapFS) Rename(oldpath string, newpath string) error

func (WritableMapFS) Stat

func (fsys WritableMapFS) Stat(name string) (fs.FileInfo, error)

func (WritableMapFS) Sub

func (fsys WritableMapFS) Sub(dir string) (fs.FS, error)

type WriterToFile

type WriterToFile interface {
	WriteToFile(rootFS WritableFS, filename string, w io.Writer) (n int64, err error)
}