drydock

README

DryDock

Simple Scaffolding Library

Usage Example

outfs := NewOSOutputFS("out")

g := NewGenerator(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..."),
        ),
    ),
)

License

MIT

Documentation

Index

• Variables
• func ModifyMarshalledFunc[V any](unmarshal func([]byte, any) error, modify func(*V) ([]byte, error)) func(contents []byte, w io.Writer) error
• func Render(files ...File) string
• type Directory
  • func Dir(name string, entries ...File) Directory
  • func DirP(name string, entries ...File) Directory
• type File
  • func ModifyFile(name string, modifier func(contents []byte, w io.Writer) error) File
  • func PlainFile(name string, contents string) File
  • func TemplatedFile(name string, template Template, data any) File
  • func TemplatedFileStr(name string, templateStr string, data any) File
• type Generator
  • func NewGenerator(output OutputFS, opts ...Option) *Generator
  • func (g *Generator) Add(files ...File) *Generator
  • func (g *Generator) Generate(ctx context.Context, files ...File) error
• type MapFSOutputFS
  • func (fsys *MapFSOutputFS) Mkdir(name string) error
  • func (fsys *MapFSOutputFS) MkdirTemp(pattern string) (OutputFS, string, error)
  • func (fsys *MapFSOutputFS) OpenFile(name string, flag int, perm fs.FileMode) (fs.File, error)
  • func (fsys *MapFSOutputFS) Remove(name string) error
  • func (fsys *MapFSOutputFS) RemoveAll(name string) error
  • func (fsys *MapFSOutputFS) Rename(oldpath string, newpath string) error
• type Option
  • func WithEmptyOutputDir(b bool) Option
  • func WithErrorOnExistingDir(b bool) Option
  • func WithErrorOnExistingFile(b bool) Option
• type OutputFS
  • func NewOSOutputFS(dir string) OutputFS
• type Template
• type WriterToModify

Examples

• Generator.Generate
• Render

Variables

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

Functions

func ModifyMarshalledFunc

func ModifyMarshalledFunc[V any](unmarshal func([]byte, any) error, modify func(*V) ([]byte, error)) func(contents []byte, w io.Writer) error

func Render

func Render(files ...File) string

Render returns a textual representation of the file structure, primarily used for debugging.

Example

files := Render(PlainFile("fileA", ""),
	Dir("dirA", PlainFile("dirAFileA", "")),
	Dir("dirB", PlainFile("dirBFileA", ""), PlainFile("dirBFileB", "")),
	PlainFile("fileD", ""),
	Dir("dirC", Dir("dirCdirA",
		PlainFile("dirCdirAFileA", ""),
		Dir("dirCdirADirA", Dir("dirCdirADirADirA",
			PlainFile("dirCdirADirADirAFileA", ""),
			PlainFile("dirCdirADirADirAFileB", ""),
		)),
	)))

fmt.Println(files)

Output:

.
├── fileA
├── dirA/
│   └── dirAFileA
├── dirB/
│   ├── dirBFileA
│   └── dirBFileB
├── fileD
└── dirC/
    └── dirCdirA/
        ├── dirCdirAFileA
        └── dirCdirADirA/
            └── dirCdirADirADirA/
                ├── dirCdirADirADirAFileA
                └── dirCdirADirADirAFileB

Types

type Directory

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

A Directory can contain files and other directories.

func Dir

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

Dir creates a new directory with the provided entries as direct children.

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 File

type File interface {
	Name() string
}

File is either a real file to be generated or a directory. Plain files must also implement io.Writer to write their content to the output file.

func ModifyFile

func ModifyFile(name string, modifier func(contents []byte, w io.Writer) error) File

ModifyFile can modify an existing file's contents. Generator.Generate will return an error, if the file doesn't exist yet.

func PlainFile

func PlainFile(name string, contents string) File

A PlainFile with the given contents.

func TemplatedFile

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

TemplatedFile will execute the template with the given data and write the resuls to the output file.

func TemplatedFileStr

func TemplatedFileStr(name string, templateStr string, data any) File

type Generator

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

func NewGenerator

func NewGenerator(output OutputFS, opts ...Option) *Generator

func (*Generator) Add

func (g *Generator) Add(files ...File) *Generator

func (*Generator) Generate

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

Example

outpath, err := os.MkdirTemp("", "drydock.ExampleGenerator_Generate-*")
if err != nil {
	panic(err)
}
defer os.RemoveAll(outpath)

outfs := NewOSOutputFS(outpath)

g := NewGenerator(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 MapFSOutputFS

type MapFSOutputFS struct {
	fstest.MapFS
	// contains filtered or unexported fields
}

MapFSOutputFS extends testing/fstest.MapFS with OutputFS capabilities.

func (*MapFSOutputFS) Mkdir

func (fsys *MapFSOutputFS) Mkdir(name string) error

func (*MapFSOutputFS) MkdirTemp

func (fsys *MapFSOutputFS) MkdirTemp(pattern string) (OutputFS, string, error)

func (*MapFSOutputFS) OpenFile

func (fsys *MapFSOutputFS) OpenFile(name string, flag int, perm fs.FileMode) (fs.File, error)

func (*MapFSOutputFS) Remove

func (fsys *MapFSOutputFS) Remove(name string) error

func (*MapFSOutputFS) RemoveAll

func (fsys *MapFSOutputFS) RemoveAll(name string) error

func (*MapFSOutputFS) Rename

func (fsys *MapFSOutputFS) Rename(oldpath string, newpath string) error

type Option

type Option func(g *Generator)

func WithEmptyOutputDir

func WithEmptyOutputDir(b bool) Option

func WithErrorOnExistingDir

func WithErrorOnExistingDir(b bool) Option

func WithErrorOnExistingFile

func WithErrorOnExistingFile(b bool) Option

type OutputFS

type OutputFS interface {
	fs.FS

	OpenFile(name string, flag int, perm fs.FileMode) (fs.File, error)

	// Mkdir creates a new directory and must return fs.ErrExist if the directory already exists.
	Mkdir(name string) error

	// Rename a given file or directory. Returned errors must be [os.LinkError] errors.
	Rename(oldpath string, newpath string) error

	// Remove the file at path or directory, if the directory is empty.
	Remove(path string) error

	// RemoveAll is like [OutputFS.Remove] but also removes any non-empty directories.
	RemoveAll(path string) error

	// MkdirTemp creates a temporary directory with the pattern, as described in [os.MkdirTemp].
	// The caller is responsible for removing and temporary directories, they will not be cleaned up automatically.
	MkdirTemp(pattern string) (OutputFS, string, error)
}

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

func NewOSOutputFS

func NewOSOutputFS(dir string) OutputFS

NewOSOutputFS creates a new [OutputsFS] backed by the real filesystem, like os.DirFS.

type Template

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

type WriterToModify

type WriterToModify interface {
	WriteModifiedTo(contents []byte, w io.Writer) error
}