domovoi

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 11, 2026 License: GPL-3.0 Imports: 16 Imported by: 8

README

DOMOVOI

License go Version

Overview

domovoi is a library to handle common IO tasks effortlessly and with versatility

Features

  • Effortless IO Operations: Simplify file handling, data streaming, and other IO tasks.
  • Seamless Integration: Works well with external tools and libraries like horus for enhanced error handling.
  • Versatile APIs: Intuitive interfaces designed for quick setup and ease of use.
  • Expandable: Easily expandable due to stable and flexible APIs.

Installation

Language-Specific
Language Command
Go go get github.com/DanielRivasMD/domovoi@latest

Usage

import "github.com/DanielRivasMD/domovoi"

Example

Configuration

domovoi comes with sane defaults for smooth operation yet can be customized via environment variables or configuration files as needed.

Development

Build from source:

git clone https://github.com/DanielRivasMD/domovoi
cd domovoi

Language-Specific Setup

Language Dev Dependencies Hot Reload
Go go >= 1.23 air (live reload)

FAQ

Q: How to resolve? A: Use the built-in functions and refer to the documentation for troubleshooting guidance.

Q: Cross-platform support? A: Yes, domovoi is designed to work seamlessly on Windows, macOS, and Linux.

License

GPL [2025] [Daniel Rivas]

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func CaptureExecCmd 

func CaptureExecCmd(command string, args ...string) (string, string, error)

CaptureExecCmd executes the specified command with provided arguments and captures its standard output and error output into separate strings. If an error occurs during execution, it returns a Horus-wrapped error with detailed context.

func CaptureSh 

func CaptureSh(script string) (string, string, error)

CaptureSh runs script under /bin/sh -c, captures stdout+stderr, wraps errors.

func ChangeDir 

func ChangeDir(newDir string) error

ChangeDir attempts to chdir into newDir. On failure it wraps the os.Chdir error with a fresh Herror, tagging it FS_ERROR and recording the target path.

func CopyFile 

func CopyFile(src, dst string) error

CopyFile copies the contents of src to dst. If dst exists, it will be overwritten.

func CreateDir 

func CreateDir(dir string, verbose bool) error

CreateDir ensures that the directory at `dir` exists. If `verbose` is true, it prints diagnostic messages before and after checking / creating. Any errors are wrapped and propagated via horus

func CreateFile 

func CreateFile(filePath string, verbose bool) horus.NotFoundAction

CreateFile returns a NotFoundAction that attempts to create a file if it doesn't exist. If the file is successfully created, the action returns (true, nil). Otherwise, it returns (false, error) with detailed diagnostic information.

func CurrentDir 

func CurrentDir() (string, error)

CurrentDir returns the base name (last component) of the current directory. It obtains the absolute path of the current directory and then extracts its base name. If an error occurs while determining the absolute path, it returns a wrapped error using Horus.

func DirExist 

func DirExist(dirPath string, notFoundAction horus.NotFoundAction, verbose bool) (bool, error)

DirExist checks if a directory exists. If it doesn't, it executes the provided notFoundAction. It returns a tuple: a boolean indicating overall success (either the directory exists or the custom action adequately handled the situation) and an error carrying detailed diagnostic context. The verbose flag enables optional logging.

func ExecCmd 

func ExecCmd(command string, args ...string) error

ExecCmd executes the specified command with the provided arguments. It configures the command to forward its output (Stdout and Stderr) to the operating system's standard streams, preserving any color codes. If executing the command fails, ExecCmd returns a wrapped error using Horus.

func ExecSh 

func ExecSh(script string) error

ExecSh runs a snippet under /bin/sh -c, forwarding stdout/stderr and wrapping any failure in a Horus Herror.

func FileExist 

func FileExist(
	filePath string,
	notFoundAction horus.NotFoundAction,
	verbose bool,
) (bool, error)

FileExist checks if filePath exists. If it does, returns (true, nil). If it does not exist and notFoundAction is nil, returns (false, nil). If notFoundAction is non-nil, it’s invoked on absence. Any real I/O error (other than “not exist”) or action-error bubbles up.

Example (AutoCreate) 
create := func(path string) (bool, error) {
	f, err := os.Create(path)
	if err != nil {
		return false, err
	}
	defer f.Close()
	_, _ = f.WriteString("# default\n")
	return true, nil
}

exists, _ := FileExist("example.conf", create, false)
fmt.Println(exists)

Output:
true
Example (Basic) 
exists, _ := FileExist("no-such-file", nil, false)
fmt.Println(exists)

Output:
false

func FindHome 

func FindHome(verbose bool) (string, error)

FindHome attempts to retrieve the current user's home directory. If verbose is true it prints diagnostics; otherwise it's silent. On error it returns a categorized *Herror.

func FormatExample 

func FormatExample(app string, usages ...[]string) string

FormatExample builds a multi‐line example block each usage is a slice of "tokens": [ command, flagOrArg, flagOrArg, ... ].

func FormatHelp 

func FormatHelp(author, email, desc string) string

FormatHelp produces the "help" header + description

func LineBreaks 

func LineBreaks(withNewline ...bool)

LineBreaks prints a decorative line break consisting of 100 grey "=" symbols. If the optional withNewline argument is true, it will also print a trailing newline. Default behavior (no args or withNewline[0]==false) is to emit no final newline.

func ListDirs 

func ListDirs(directory string) ([]string, error)

ListDirs returns a slice of names for all subdirectories in the provided directory.

func ListFiles 

func ListFiles(directory string) ([]string, error)

ListFiles returns a slice of names for all regular files in the provided directory. If the directory cannot be read, it returns a wrapped error using horus.

func PrintCentered 

func PrintCentered(msg string)

PrintCentered prints msg centered in a 100-column width, surrounding it with “=” fills and one space padding on each side.

func ReadDir 

func ReadDir(path string, verbose bool) ([]os.DirEntry, error)

ReadDir reads the directory named by path and returns a list of directory entries. If verbose is true, it prints diagnostic messages before and after the read.

func RecallDir 

func RecallDir() (string, error)

RecallDir returns the current working directory. On failure, it returns a wrapped error with diagnostic details using Horus.

func RemoveFile 

func RemoveFile(filePath string, verbose bool) horus.NotFoundAction

RemoveFile returns a NotFoundAction that attempts to delete a file if it exists. If the file is successfully removed (or already missing), it returns (true, nil). Otherwise, it returns (false, error) with detailed diagnostic information.

func SetGlobalDocsConfig added in v0.2.0 

func SetGlobalDocsConfig(fs embed.FS, info AppInfo)

SetGlobalDocsConfig must be called once before GlobalDocs.

func Walk 

func Walk(processor FileProcessor) fs.WalkDirFunc

Walk returns an fs.WalkDirFunc that applies the given processor function to each non-directory file. Hidden files are ignored, and any encountered errors are wrapped and propagated using Horus.

Types

type AppInfo 

type AppInfo struct {
	Name    string
	Version string
	Author  string
	Email   string
}

AppInfo holds metadata about the application.

type CommandOpt 

type CommandOpt func(*cobra.Command)

CommandOpt is a function that configures a cobra.Command.

func WithAliases 

func WithAliases(aliases []string) CommandOpt

WithAliases sets additional aliases for the command.

func WithArgs 

func WithArgs(validator cobra.PositionalArgs) CommandOpt

WithArgs sets the positional argument validator.

func WithDisableFlagParsing 

func WithDisableFlagParsing(disable bool) CommandOpt

WithDisableFlagParsing disables flag parsing for the command.

func WithPostRun 

func WithPostRun(postRun func(*cobra.Command, []string)) CommandOpt

WithPostRun sets a function to run after the command's Run.

func WithPreRun 

func WithPreRun(preRun func(*cobra.Command, []string)) CommandOpt

WithPreRun sets a function to run before the command's Run.

func WithSilenceErrors 

func WithSilenceErrors(silence bool) CommandOpt

WithSilenceErrors silences errors from being printed.

func WithSilenceUsage 

func WithSilenceUsage(silence bool) CommandOpt

WithSilenceUsage silences usage information on error.

func WithValidArgs 

func WithValidArgs(args []string) CommandOpt

WithValidArgs sets the valid positional arguments for shell completion.

func WithValidArgsFunction 

func WithValidArgsFunction(f func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)) CommandOpt

WithValidArgsFunction sets a custom shell completion function.

type DocEntry 

type DocEntry struct {
	Use                   string     `json:"use"`
	Aliases               []string   `json:"aliases,omitempty"`
	Hidden                bool       `json:"hidden,omitempty"`
	Short                 string     `json:"short,omitempty"`
	Long                  string     `json:"long"`
	ExampleUsages         [][]string `json:"example_usages,omitempty"`
	ValidArgs             []string   `json:"valid_args,omitempty"`
	DisableFlagsInUseLine bool       `json:"disable_flags_in_use_line,omitempty"`
}

DocEntry represents a command's documentation as stored in the JSON file.

type Docs 

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

Docs manages loading and accessing embedded command documentation.

func GlobalDocs added in v0.2.0 

func GlobalDocs() (*Docs, error)

GlobalDocs returns the singleton Docs instance, creating it on first call.

func NewDocs 

func NewDocs(fs embed.FS, info AppInfo) (*Docs, error)

NewDocs creates a Docs instance that reads the embedded file at path "docs.json". The fs parameter should point to the embed.FS that contains the JSON file. Returns an error if the file cannot be read or parsed.

func (*Docs) CommandExists 

func (d *Docs) CommandExists(key string) (bool, error)

CommandExists checks if a command key exists.

func (*Docs) GetAllEntries 

func (d *Docs) GetAllEntries() (map[string]DocEntry, error)

GetAllEntries returns a copy of the raw entries map.

func (*Docs) GetEntry 

func (d *Docs) GetEntry(key string) (DocEntry, error)

GetEntry returns the raw DocEntry for a command key.

func (*Docs) GetExample 

func (d *Docs) GetExample(key string) (string, error)

GetExample returns the formatted example block for a command.

func (*Docs) GetHelp 

func (d *Docs) GetHelp(key string) (string, error)

GetHelp returns the formatted long help for a command.

func (*Docs) GetShort 

func (d *Docs) GetShort(key string) (string, error)

GetShort returns the short description for a command.

func (*Docs) GetUse 

func (d *Docs) GetUse(key string) (string, error)

GetUse returns the use line for a command.

func (*Docs) IsHidden 

func (d *Docs) IsHidden(key string) (bool, error)

IsHidden reports whether a command should be hidden.

func (*Docs) ListCommands 

func (d *Docs) ListCommands() ([]string, error)

ListCommands returns all command keys present in the documentation.

func (*Docs) MakeCmd 

func (d *Docs) MakeCmd(key string, run func(*cobra.Command, []string), opts ...CommandOpt) (*cobra.Command, error)

MakeCmd creates a cobra.Command from the documentation identified by key. The run function is the command's execution logic. Additional options can be provided. Returns an error if the key is not found or documentation cannot be loaded.

type FileProcessor 

type FileProcessor func(string)

FileProcessor defines the type for a file processing function.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.