parts

README

go-parts

Golang Debian run-parts package

Parts is a Go (golang) package that is used to traverse or read files in one or more directories using Debian's run-parts layout. Filters can be used to only include:

• Files that match a regular expression.
• Files that match a file type mask, e.g., regular files, directories, etc.
• Files that match a file permission mask, e.g., executables.

Directories are specified in a slice. Files from directories appearing earlier in the slice that have the same basename as a file from a directory appearing later in the slice take precedence. Example: using the following directory layouts:

── etc
│   ├── 10-both.conf
│   ├── 10-only-etc.conf
│   ├── 20-only-etc.conf
│   └── 30-symlink.conf -> ../usr/lib/30-symlink.conf
├── test.conf
└── usr
    └── lib
        ├── 10-both.conf
        ├── 10-executable.sh
        ├── 10-only-lib.conf
        ├── 20-only-lib.conf
        ├── 30-symlink.conf
        ├── 40-noconf
        └── nodigits.conf

The etc/10-both.conf file is used and the /usr/lib/10-both.conf is ignored.

After duplicates are resolved, the files are lexically sorted (optionally in reverse order).

Using the above layout and using a ".*.conf" file name filter we can use parts.Readdirnames() to list the files in run-parts order, e.g.,

etc/10-both.conf
etc/10-only-etc.conf
usr/lib/10-only-lib.conf
etc/20-only-etc.conf
usr/lib/20-only-lib.conf
etc/30-symlink.conf
usr/lib/nodigits.conf
test.conf

Or we can read the concatinated contents of all these files using parts.Read().

Documentation

Documentation can be found at GoDoc

Installation

$ go get -u github.com/apatters/go-parts

Examples

Parts.Readdirnames()

	config, _ := parts.NewConfig(
		false,
		parts.ExecutableModeTypeFilter,
		parts.ExecutableModePermFilter,
		parts.DefaultRegExpFilter)

	p := parts.NewParts(testDataPaths, config)
	names, _ := p.Readdirnames(0)
	for _, name := range names {
		fmt.Println(name)
	}

Parts.Read()

	config, _ := parts.NewConfig(
		false,
		parts.DefaultModeTypeFilter,
		parts.DefaultModePermFilter,
		`\.conf$`)

	p := parts.NewParts(testDataPaths, config)
	defer p.Close()
	b, _ := ioutil.ReadAll(p)
	contents := string(b)
	fmt.Print(contents)

License

MIT.

Thanks

Thanks to Secure64 for contributing this code.

Documentation

Overview

Package parts is used to traverse or read files in one or more directories using Debian's run-parts layout. Filters can be used to only include:

• Files that match a regular expression.
• Files that match a file type mask, e.g., regular files, directories, etc.
• Files that match a file permission mask, e.g., executables.

Directories are specified in a slice. Files from directories appearing earlier in the slice that have the same base name as a file from a directory appearing later in the slice take precedence. e.g., using the following directory layouts:

── etc
│   ├── 10-both.conf
│   ├── 10-only-etc.conf
│   ├── 20-only-etc.conf
│   └── 30-symlink.conf -> ../usr/lib/30-symlink.conf
├── test.conf
└── usr
    └── lib
        ├── 10-both.conf
        ├── 10-executable.sh
        ├── 10-only-lib.conf
        ├── 20-only-lib.conf
        ├── 30-symlink.conf
        ├── 40-noconf
        └── nodigits.conf

The etc/10-both.conf file is used and the /usr/lib/10-both.conf is ignored if etc is configured ahead of /usr/lib.

After duplicates are resolved, the files are lexically sorted (optionally in reverse order).

Using the above layout and using a ".*\.conf" file name filter we can use parts.Readdirnames() to list the files in run-parts order, e.g.,

etc/10-both.conf
etc/10-only-etc.conf
usr/lib/10-only-lib.conf
etc/20-only-etc.conf
usr/lib/20-only-lib.conf
etc/30-symlink.conf
usr/lib/nodigits.conf
test.conf

Or we can read the concatenated contents of all these files using parts.Read().

Index

• Constants
• type Config
  • func NewConfig(reverse bool, modeTypeFilter FileMode, modePermFilter FileMode, ...) (*Config, error)
  • func NewDefaultConfig() *Config
• type FileInfo
  • func (i FileInfo) Mode() FileMode
• type FileMode
  • func LstatMode(name string) (FileMode, error)
  • func StatMode(name string) (FileMode, error)
  • func (m FileMode) IsDir() bool
  • func (m FileMode) IsExecutable() bool
  • func (m FileMode) IsRegular() bool
  • func (m FileMode) Perm() FileMode
  • func (m FileMode) String() string
• type Parts
  • func NewParts(paths []string, config *Config) *Parts
  • func (p *Parts) Close() error
  • func (p *Parts) Read(b []byte) (int, error)
  • func (p *Parts) Readdirnames(n int) ([]string, error)
• type Partser

Examples

• LstatMode
• Parts.Read
• Parts.Readdirnames
• StatMode

Constants

const (
	// The single letters are the abbreviations
	// used by the String method's formatting.
	ModeDir        = FileMode(os.ModeDir)        // d: is a directory
	ModeAppend     = FileMode(os.ModeAppend)     // a: append-only
	ModeExclusive  = FileMode(os.ModeExclusive)  // l: exclusive use
	ModeTemporary  = FileMode(os.ModeTemporary)  // T: temporary file; Plan 9 only
	ModeSymlink    = FileMode(os.ModeSymlink)    // L: symbolic link
	ModeDevice     = FileMode(os.ModeDevice)     // D: device file
	ModeNamedPipe  = FileMode(os.ModeNamedPipe)  // p: named pipe (FIFO)
	ModeSocket     = FileMode(os.ModeSocket)     // S: Unix domain socket12
	ModeSetuid     = FileMode(os.ModeSetuid)     // u: setuid
	ModeSetgid     = FileMode(os.ModeSetgid)     // g: setgid
	ModeCharDevice = FileMode(os.ModeCharDevice) // c: Unix character device, when ModeDevice is set
	ModeSticky     = FileMode(os.ModeSticky)     // t: sticky
	ModeRegular    = 1 << (31 - iota)            // f: regular file

	// Mask for the type bits.
	ModeType = ModeDir | ModeSymlink | ModeNamedPipe | ModeSocket | ModeDevice | ModeRegular

	// Unix permission bits
	ModePerm FileMode = 0777
)

const (
	DefaultModeTypeFilter    = ModeRegular
	DefaultModePermFilter    = ModePerm
	ExecutableModePermFilter = 0111
	ExecutableModeTypeFilter = ModeRegular
	DefaultRegExpFilter      = ".*"
)

Types

type Config

type Config struct {
	Reverse        bool
	ModeTypeFilter FileMode
	ModePermFilter FileMode
	RegExpFilter   *regexp.Regexp
}

Config is used to pass parameter to NewConfig.

func NewConfig

func NewConfig(reverse bool, modeTypeFilter FileMode, modePermFilter FileMode, regExpFilter string) (*Config, error)

NewConfig constructor. Can fail if regular expressions do not compile.

func NewDefaultConfig

func NewDefaultConfig() *Config

NewDefaultConfig returns a default Config constructor.

type FileInfo

type FileInfo struct {
	os.FileInfo
}

FileInfo extends the os.FileInfo struct.

func (FileInfo) Mode

func (i FileInfo) Mode() FileMode

Mode returns the file mode bits of the file with an adjustment made for regular files.

type FileMode

type FileMode os.FileMode

FileMode is an extension of the os.FileMode struct. It adds a ModeRegular bit to make testing for a regular file explicit.

func LstatMode

func LstatMode(name string) (FileMode, error)

LstatMode returns the FileMode for the named path. If the path is a symbolic link, the returned FileMode describes the symbolic link. If there is an error, it will be of type *PathError.

Example

for _, path := range testDataSymlinks {
	mode, _ := parts.LstatMode(path)
	fmt.Println(mode)
}

Output:
Lrwxrwxrwx

func StatMode

func StatMode(name string) (FileMode, error)

StatMode returns the FileMode for the named path. If there is an error, it will be of type *PathError.

Example

for _, path := range testDataExecutables {
	mode, _ := parts.StatMode(path)
	fmt.Println(mode)
}

Output:
frwxr-xr-x

func (FileMode) IsDir

func (m FileMode) IsDir() bool

IsDir reports whether m describes a directory.

func (FileMode) IsExecutable

func (m FileMode) IsExecutable() bool

IsExecutable reports whether m describes an executablexs file.

func (FileMode) IsRegular

func (m FileMode) IsRegular() bool

IsRegular reports whether m describes a regular file.

func (FileMode) Perm

func (m FileMode) Perm() FileMode

Perm returns the permission bits of the file mode.

func (FileMode) String

func (m FileMode) String() string

type Parts

type Parts struct {
	Paths  []string
	Config *Config
	// contains filtered or unexported fields
}

Parts encapsulates data and functions used to process "run-parts" directories.

func NewParts

func NewParts(paths []string, config *Config) *Parts

NewParts is the Parts constructor. A default configuration is used if config is nil.

func (*Parts) Close

func (p *Parts) Close() error

Close closes all files opened by Read.

func (*Parts) Read

func (p *Parts) Read(b []byte) (int, error)

Read reads the contents of the parts directory into buffer b.

Example

config, _ := parts.NewConfig(
	false,
	parts.DefaultModeTypeFilter,
	parts.DefaultModePermFilter,
	`\.conf$`)

p := parts.NewParts(testDataPaths, config)
defer p.Close()
b, _ := ioutil.ReadAll(p)
contents := string(b)
fmt.Print(contents)

Output:
10-both.conf
10-only-etc.conf
10-only-lib.conf
20-only-etc.conf
20-only-lib.conf
30-symlink.conf
nodigits.conf
test.conf

func (*Parts) Readdirnames

func (p *Parts) Readdirnames(n int) ([]string, error)

Readdirnames returns a list of files in paths that follow the "run-parts" naming convention.

Example

fmt.Println("List executable files in run-parts order:")
config, _ := parts.NewConfig(
	false,
	parts.ExecutableModeTypeFilter,
	parts.ExecutableModePermFilter,
	parts.DefaultRegExpFilter)
p := parts.NewParts(testDataPaths, config)
names, _ := p.Readdirnames(0)
for _, name := range names {
	fmt.Printf("\t%s\n", name)
}

fmt.Println("\nList files with extension '.conf' in run-parts order:")
config, _ = parts.NewConfig(
	false,
	parts.DefaultModeTypeFilter,
	parts.DefaultModePermFilter,
	`\.conf$`)
p = parts.NewParts(testDataPaths, config)
names, _ = p.Readdirnames(0)
for _, name := range names {
	fmt.Printf("\t%s\n", name)
}

fmt.Println("\nList files with extension '.conf' in reverse run-parts order:")
config, _ = parts.NewConfig(
	true,
	parts.DefaultModeTypeFilter,
	parts.DefaultModePermFilter,
	`\.conf$`)
p = parts.NewParts(testDataPaths, config)
names, _ = p.Readdirnames(0)
for _, name := range names {
	fmt.Printf("\t%s\n", name)
}

Output:
List executable files in run-parts order:
	testdata/usr/lib/10-executable.sh

List files with extension '.conf' in run-parts order:
	testdata/etc/10-both.conf
	testdata/etc/10-only-etc.conf
	testdata/usr/lib/10-only-lib.conf
	testdata/etc/20-only-etc.conf
	testdata/usr/lib/20-only-lib.conf
	testdata/etc/30-symlink.conf
	testdata/usr/lib/nodigits.conf
	testdata/test.conf

List files with extension '.conf' in reverse run-parts order:
	testdata/test.conf
	testdata/usr/lib/nodigits.conf
	testdata/etc/30-symlink.conf
	testdata/usr/lib/20-only-lib.conf
	testdata/etc/20-only-etc.conf
	testdata/usr/lib/10-only-lib.conf
	testdata/etc/10-only-etc.conf
	testdata/etc/10-both.conf

type Partser

type Partser interface {
	Readdirnames(int) ([]string, error)
	Read([]byte) (int, error)
	Close() error
}

Partser implements all functions needed for a ReadCloser and adds the os.File.Readdirnames method.