From: Mattia Cabrini Date: Sat, 2 Mar 2024 13:32:21 +0000 (+0100) Subject: Add comment X-Git-Tag: v0.0.6 X-Git-Url: https://git.theboydaily.dev/mattia?a=commitdiff_plain;h=0ad2b8f6429ad385ca2941a5bebf35c9059fbe21;p=go-utility.git Add comment --- diff --git a/colour.go b/colour.go index f3cd5df..59fe5cc 100644 --- a/colour.go +++ b/colour.go @@ -15,6 +15,7 @@ var ( White = "\033[97m" ) +// Set colours strings to "" func NotInteractive() { Reset = "" Red = "" @@ -27,6 +28,7 @@ func NotInteractive() { White = "" } +// Reset colours strings to their values func Interactive() { Reset = "\033[0m" Red = "\033[31m" diff --git a/db.go b/db.go index 6970bbd..4fddc11 100644 --- a/db.go +++ b/db.go @@ -5,11 +5,26 @@ package utility import "database/sql" +/* +To commit or rollback a transaction: + + - If err is nil, tx is committed; + - If err is not nil, tx is rolled back. + +Parameters: + + - tx *sql.Tx; + - err error. + +Returns: + + - err error: an error generated by tx.Commit or by tx.Rollback. +*/ func CommitTx(tx *sql.Tx, err error) (_ error) { if err == nil { err = tx.Commit() } else { - tx.Rollback() + err = tx.Rollback() } return AppendError(err) diff --git a/editor.go b/editor.go index a5a17b6..6d9d632 100644 --- a/editor.go +++ b/editor.go @@ -8,6 +8,20 @@ import ( "os/exec" ) +/* +To run an editor on the terminal. + +Editor merely runs the editor program (param editorPath) by passing as first parameter a file path (param path) + +Parameters: + + - editorPath string: the path to the editor binary; + - path string: the path to wich the edited file will be saved. + +Returns: + + - err error: an error if exec.Command.Run shoud generate one. +*/ func Editor(editorPath string, path string) (err error) { editor := exec.Command(editorPath, path) editor.Stdin = os.Stdin diff --git a/error.go b/error.go index 5440d2d..960157d 100644 --- a/error.go +++ b/error.go @@ -8,6 +8,8 @@ import ( "runtime" ) +// Mypanic +// If err is not nil logs a FATAL error message func Mypanic(err error) { if err == nil { return @@ -16,6 +18,29 @@ func Mypanic(err error) { Logf(FATAL, "%v", err) } +/* +Takes a funcion `f` that might return an error, a void function `pre`, a void function `post` + +It is supposed to be used to handle deferred function calls that returns an error without ugly sintax such as: + + defer func() { + err := fp.Close() + + if err != nil { + panic(err) + } + }() + +Using Deferrable: + + defer Deferrable(fp.Close, nil, nil) + +What it does: + + - If pre is not nil, executes pre(); + - Executes f() and panic (using Mypanic) if `f` result is not nil; + - If does not panic and post is not nil, executes post. +*/ func Deferrable(f func() error, pre func(), post func()) { if pre != nil { pre() @@ -26,6 +51,7 @@ func Deferrable(f func() error, pre func(), post func()) { } } +// Appends to error the funcion in wich the error has been generated func AppendError(err error) error { if err == nil { return nil @@ -34,6 +60,8 @@ func AppendError(err error) error { return fmt.Errorf("%s: %v", fileName, err) } +// Returns the third to last function on the stack +// Should be used only in AppendError func trace() (receipts []string) { var p = make([]uintptr, 10) runtime.Callers(2, p) diff --git a/less.go b/less.go index fe3b863..e99a006 100644 --- a/less.go +++ b/less.go @@ -9,11 +9,16 @@ import ( "os/exec" ) +// Show a message on the terminal via less by executing +// echo {string} piped through less. +// The string is generated using Printf-like format and arguments func Lessf(format string, args ...interface{}) error { str := fmt.Sprintf(format, args...) return less(str) } +// Show the string `str` on the terminal via less by executing +// echo {str} piped through less func less(str string) (err error) { echo := exec.Command("echo", str) echo.Stdin = os.Stdin diff --git a/log.go b/log.go index e7cce03..36da64c 100644 --- a/log.go +++ b/log.go @@ -13,13 +13,14 @@ import ( type LogLevel int const ( - FATAL LogLevel = (1 << iota) >> 1 - ERROR - WARNING - INFO - VERBOSE + FATAL LogLevel = (1 << iota) >> 1 // To log an error and exit + ERROR // To log and error + WARNING // To log a warning + INFO // To log some information + VERBOSE // To log some detailed information (meant to debug) ) +// Maps log levels to strings var levelToString = map[LogLevel]string{ FATAL: " FATAL ", ERROR: " ERROR ", @@ -28,6 +29,7 @@ var levelToString = map[LogLevel]string{ VERBOSE: "VERBOSE", } +// Maps log levels to colours func getLevelColor(level LogLevel) string { switch level { case FATAL: @@ -43,14 +45,21 @@ func getLevelColor(level LogLevel) string { return Gray } +// To log synchronously var logGuard *sync.Mutex = &sync.Mutex{} -var MaximumLevel LogLevel = WARNING +// Minimum level to log +// If it is WARNING, INFO and VERBOSE are not logged +// If it is ERROR, WARNING, INFO and WARNING are not logged +// ... and so on ... +var MinimumLevel LogLevel = WARNING + +// Log a message with a specific log level; Format and args are Printf-like func Logf(level LogLevel, format string, args ...interface{}) { logGuard.Lock() defer logGuard.Unlock() - if level > MaximumLevel { + if level > MinimumLevel { return } @@ -75,6 +84,7 @@ func logfCompose(level LogLevel, format string) string { return format } +// Log a message on *testing.T with a specific log level; Format and args are Printf-like func Tlogf(t *testing.T, level LogLevel, format string, args ...interface{}) { logGuard.Lock() defer logGuard.Unlock() diff --git a/method.go b/method.go index aec2366..2d247e4 100644 --- a/method.go +++ b/method.go @@ -7,6 +7,8 @@ import ( "reflect" ) +// Represent an object method, callable by invoking F and passing the very same +// parameters that would be passed to that object method (which means NOT the receiver) type Method struct { to reflect.Method numIn int @@ -24,10 +26,16 @@ func newMethod(to reflect.Method, callable GenericFunc) (m *Method) { return } +// Retuns the numer of parameters that F expects func (m *Method) NumIn() int { return m.numIn } +/* +Takes an integer `i` and retuns the i-th parameter kind that F would expect. + +Note that F do take as parameters the object method's parameters but NOT the method receiver +*/ func (m *Method) ParamKind(i int) reflect.Kind { return m.to.Type.In(i + 1).Kind() } diff --git a/reflect.go b/reflect.go index 12b3ee0..142ca84 100644 --- a/reflect.go +++ b/reflect.go @@ -52,6 +52,9 @@ func newGenericFunc(obj interface{}, methodTO reflect.Method, methodVO reflect.V } } +// Giveng an obj interface{}, returns a *Method from that obj. +// GetMethod seeks a method that has name equal to name + suffix. +// `suffix` might just be an empty string. func GetMethod(obj interface{}, name string, suffix string) *Method { to := reflect.TypeOf(obj) vo := reflect.ValueOf(obj) @@ -67,6 +70,9 @@ func GetMethod(obj interface{}, name string, suffix string) *Method { return nil } +// Giveng an obj interface{}, returns an interface{} which is a propery value of that onj. +// GetProperty seeks a property that has name equal to name + suffix. +// `suffix` might just be an empty string. func GetProperty(obj interface{}, name string, suffix string, tags ...string) interface{} { to := reflect.TypeOf(obj) vo := reflect.ValueOf(obj) diff --git a/sync.go b/sync.go index 146ae99..3d3e77d 100644 --- a/sync.go +++ b/sync.go @@ -13,6 +13,18 @@ type rlockable interface { RUnlock() } +/* +Lock a lockable and retun a funcion to unlock the lockable. + +The meaning is to avoid ugly syntax such as: + + mu.Lock() + defer mu.Unlock() + +Which became: + + defer Monitor(mu)() +*/ func Monitor(mu lockable) func() { mu.Lock() return func() { @@ -20,6 +32,18 @@ func Monitor(mu lockable) func() { } } +/* +Lock a rlockable and retun a funcion to unlock the rlockable. + +The meaning is to avoid ugly syntax such as: + + mu.RLock() + defer mu.RUnlock() + +Which became: + + defer RMonitor(mu)() +*/ func RMonitor(mu rlockable) func() { mu.RLock() return func() { diff --git a/sync_fmt.go b/sync_fmt.go index db77bd3..d8d0fed 100644 --- a/sync_fmt.go +++ b/sync_fmt.go @@ -12,12 +12,14 @@ import ( var syncIoGuard = &sync.Mutex{} +// Fprintf but synced func Fprintf(fp io.Writer, format string, args ...any) { defer Monitor(syncIoGuard)() fmt.Fprint(fp, format, args) } +// Printf but synced func Printf(format string, args ...any) { defer Monitor(syncIoGuard)()