cliargdax

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2023 License: MIT Imports: 4 Imported by: 0

README

cliargdax Go Reference CI Status MIT License

A dax for command-line arguments in Golang applications.

Dax is a module in sabi framework for data access. This package provides DaxSrc and DaxConn structs for command-line argument operations.

This package uses cliargs package to parse command-line arguments and store the results of parsing.

Import this package

import "github.com/sttk/cliargdax"

Usage

The usage of this library is described on the overview in the go package document.

See https://pkg.go.dev/github.com/sttk/cliargdax#pkg-overview

Supporting Go versions

This library supports Go 1.18 or later.

Actual test results for each Go versions:
% gvm-fav
Now using version go1.18.10
go version go1.18.10 darwin/amd64
ok  	github.com/sttk/cliargdax	0.150s	coverage: 100.0% of statements

Now using version go1.19.13
go version go1.19.13 darwin/amd64
ok  	github.com/sttk/cliargdax	0.157s	coverage: 100.0% of statements

Now using version go1.20.8
go version go1.20.8 darwin/amd64
ok  	github.com/sttk/cliargdax	0.161s	coverage: 100.0% of statements

Now using version go1.21.1
go version go1.21.1 darwin/amd64
ok  	github.com/sttk/cliargdax	0.174s	coverage: 100.0% of statements

Back to go1.21.1
Now using version go1.21.1

License

Copyright (C) 2023 Takayuki Sato

This program is free software under MIT License.
See the file LICENSE in this distribution for more details.

Documentation

Overview

Package github.com/sttk/cliargdax is a dax in sabi framework for data access.

This package uses github.com/sttk/cliargs package to parse command-line arguments and store the results of parsing.

Usage of dax source

This package provides a dax source named DaxSrc.

This dax source can be used both as a global and local dax source. However, since command-line arguments can be obtained globally, it is typically used as a global dax source. And it would be appropriate to declare its usage within init function. 

import "github.com/sttk/cliargdax"

func init() {
    sabi.Uses("cliopts", cliargdax.NewDaxSrc())
}

A DaxSrc instance can be instantiated by the functions: NewDaxSrc, NewDaxSrcWithOptCfgs, NewDaxSrcForOptions.

NewDaxSrc function creates a DaxSrc instance without configuration (see above). And it's Setup method separates command-line arguments to normal arguments and options only by their formats.

NewDaxSrcWithOptCfgs function creates a DaxSrc instance with an array of cliargs.OptCfg. 

optCfgs := []cliargs.OptCfg{
  cliargs.OptCfg{ ... },
  ... ,
}
sabi.Uses("cliopts", cliargdax.NewDaxSrcWithOptCfgs(optCfgs))

And it's Setup method parses command-line arguments with the array. This configuration array can be retrieve by using DaxConn#OptCfgs method.

NewDaxSrcForOptions function creates a DaxSrc instance with a pointer of any type struct instance that stores results of command-line argument parsing. 

type MyOptions struct { ... }
opts := MyOptions{ ... }
sabi.Uses("cliopts", cliargdax.NewDaxSrcForOptions(&opts)

And it's Setup method parses command-line arguments with an array of cliargs.OptCfg that is created from the option store instance. These configuration array and store instance can be retrieve by using DaxConn#OptCfgs and DaxConn#Options methods.

Usage of dax connection

This package provides a dax connection named DaxConn. This dax connection is created by DaxSrc#CreateDaxConn method.

Within dax implementations using command-line arguments, this dax connection is obtained by sabi.GetDaxConn method. And by this dac connection, the results of command-line argument parsing can be obtained. 

func (dax MyDax) doSomeDataAccess() errs.Err {
    conn, err := sabi.GetDaxConn[cliargdax.DaxConn](dax, "cliopts")
    if err.IsNotOk() {
        return err
    }

    var cmd cliargs.Cmd = conn.Cmd()
    var optCfgs []cliargs.OptCfg = conn.OptCfgs()
    var options *MyOptions = conn.Options().(*MyOptions)

    return errs.Ok()
}

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DaxConn 

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

DaxConn is the dax connection struct for command line argument operations. In addition to methods for transactions: Commit, IsCommitted, Rollback, ForceBack, and Close, this structure provides methods to retrieve the cliargs.Cmd struct that stores the results of command line argument parsing, an array of cliargs.OptCfg struct for storing command line argument configurations, and methods to set and retrieve any type struct instance generated from the results of command line argument parsing.

func (DaxConn) Close 

func (conn DaxConn) Close()

Close is the one of the required methods for a struct that inherits sabi.DaxConn. This method is empty and does nothing.

func (DaxConn) Cmd 

func (conn DaxConn) Cmd() cliargs.Cmd

Cmd is the method to retrieve a cliargs.Cmd struct instance that stores the results of command line argument parsing.

Example 
os.Args = []string{"path/to/app", "--foo", "bar"}

base := sabi.NewDaxBase()
defer base.Close()

base.Uses("cliarg", cliargdax.NewDaxSrc())

conn, err := sabi.GetDaxConn[cliargdax.DaxConn](base, "cliarg")
fmt.Printf("err.IsOk = %t\n", err.IsOk())

cmd := conn.Cmd()
fmt.Printf("cmd.Name = %s\n", cmd.Name)
fmt.Printf("cmd.Args = %v\n", cmd.Args())
fmt.Printf("cmd.HasOpts: foo = %t\n", cmd.HasOpt("foo"))

Output:

err.IsOk = true
cmd.Name = app
cmd.Args = [bar]
cmd.HasOpts: foo = true

func (DaxConn) Commit 

func (conn DaxConn) Commit(ag sabi.AsyncGroup) errs.Err

Commit is the one of the required methods for a struct that inherits sabi.DaxConn. It is called by sabi.Txn function. This method is empty and only returns a result of errs.Ok().

func (DaxConn) ForceBack 

func (conn DaxConn) ForceBack(ag sabi.AsyncGroup)

ForceBack is the one of the required methods for a struct that inherits sabi.DaxConn. This method is empty and does nothing.

func (DaxConn) IsCommitted 

func (conn DaxConn) IsCommitted() bool

IsCommitted is the one of the required methods for a struct that inherits sabi.DaxConn. It is called by sabi.Txn function. This method always returns true.

func (DaxConn) OptCfgs 

func (conn DaxConn) OptCfgs() []cliargs.OptCfg

OptCfgs is the method to retrieve an array of cliargs.OptCfg struct instances. This array is either passed as an argument to NewDaxSrcWithOptCfgs function or parsed from the struct instance passed as an argument to NewDaxSrcForOptions function.

Example 
os.Args = []string{"path/to/app", "--foo", "bar"}

base := sabi.NewDaxBase()
defer base.Close()

opts := struct {
	Foo bool `optcfg:"foo"`
}{}
base.Uses("cliarg", cliargdax.NewDaxSrcForOptions(&opts))

conn, err := sabi.GetDaxConn[cliargdax.DaxConn](base, "cliarg")
fmt.Printf("err.IsOk = %t\n", err.IsOk())

optCfgs := conn.OptCfgs()
fmt.Printf("len(optCfgs) = %d\n", len(optCfgs))
fmt.Printf("optCfgs[0].Name = %v\n", optCfgs[0].Name)

Output:

err.IsOk = true
len(optCfgs) = 1
optCfgs[0].Name = foo

func (DaxConn) Options 

func (conn DaxConn) Options() any

Options is the method to retrieve a struct instance of any type, which is either passed as an argument to NewDaxSrcForOptions or set by DaxConn#SetOptions method.

Example 
os.Args = []string{"path/to/app", "--foo", "bar"}

base := sabi.NewDaxBase()
defer base.Close()

type MyOptions struct {
	Foo bool `optcfg:"foo"`
}
base.Uses("cliarg", cliargdax.NewDaxSrcForOptions(&MyOptions{}))

conn, err := sabi.GetDaxConn[cliargdax.DaxConn](base, "cliarg")
fmt.Printf("err.IsOk = %t\n", err.IsOk())

options := conn.Options().(*MyOptions)
fmt.Printf("options.Foo = %t\n", options.Foo)

Output:

err.IsOk = true
options.Foo = true

func (DaxConn) Rollback 

func (conn DaxConn) Rollback(ag sabi.AsyncGroup)

Rollback is the one of the required methods for a struct that inherits sabi.DaxConn. This method never be called because IsCommitted always returns true.

func (DaxConn) SetOptions 

func (conn DaxConn) SetOptions(opts any)

SetOptions is the method to set a struct instance of any type to a DaxSrc instance through this DaxConn instance.. Because this argument is set to a DaxSrc instance, it is persists even after the transaction has ended. If the DaxSrc instance is global, the argument instance will persist until the application is terminated (until the sabi.Close function is called).

Example 
package main

import (
	"fmt"
	"os"

	"github.com/sttk/cliargdax"
	"github.com/sttk/sabi"
)

func main() {
	os.Args = []string{"path/to/app", "--foo", "bar"}

	base := sabi.NewDaxBase()
	defer base.Close()

	base.Uses("cliarg", cliargdax.NewDaxSrc())

	conn, err := sabi.GetDaxConn[cliargdax.DaxConn](base, "cliarg")
	fmt.Printf("err.IsOk = %t\n", err.IsOk())

	fmt.Printf("options = %v\n", conn.Options())

	type MyOptions struct {
		Foo bool
	}
	conn.SetOptions(&MyOptions{Foo: true})

	options := conn.Options().(*MyOptions)
	fmt.Printf("options.Foo = %t\n", options.Foo)

}

Output:

err.IsOk = true
options = <nil>
options.Foo = true

type DaxSrc 

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

DaxSrc is the dax source struct for command line argument operations. This struct stores the results of command line argument parsing, and provides them via a DaxConn instance.

func NewDaxSrc 

func NewDaxSrc() *DaxSrc

NewDaxSrc is the constructor function of cliargdax.DaxSrc struct.

Example 
os.Args = []string{"path/to/app", "--foo", "bar"}

base := sabi.NewDaxBase()
defer base.Close()

base.Uses("cliarg", cliargdax.NewDaxSrc())

conn, err := sabi.GetDaxConn[cliargdax.DaxConn](base, "cliarg")
fmt.Printf("err.IsOk = %t\n", err.IsOk())

cmd := conn.Cmd()
fmt.Printf("cmd.Name = %s\n", cmd.Name)
fmt.Printf("cmd.Args = %v\n", cmd.Args())
fmt.Printf("cmd.HasOpts: foo = %t\n", cmd.HasOpt("foo"))
fmt.Printf("optCfgs = %v\n", conn.OptCfgs())
fmt.Printf("options = %v\n", conn.Options())

Output:

err.IsOk = true
cmd.Name = app
cmd.Args = [bar]
cmd.HasOpts: foo = true
optCfgs = []
options = <nil>

func NewDaxSrcForOptions 

func NewDaxSrcForOptions(opts any) *DaxSrc

NewDaxSrcForOptions is the constructor function for cliargdax.DaxSrc struct that takes an instnace of a struct of any type, which stores the results of command line argument parsing.

Example 
os.Args = []string{"path/to/app", "--foo", "bar"}

base := sabi.NewDaxBase()
defer base.Close()

optCfgs := []cliargs.OptCfg{
	cliargs.OptCfg{
		Name: "foo",
	},
}
base.Uses("cliarg", cliargdax.NewDaxSrcWithOptCfgs(optCfgs))

conn, err := sabi.GetDaxConn[cliargdax.DaxConn](base, "cliarg")
fmt.Printf("err.IsOk = %t\n", err.IsOk())

cmd := conn.Cmd()
fmt.Printf("cmd.Name = %s\n", cmd.Name)
fmt.Printf("cmd.Args = %v\n", cmd.Args())
fmt.Printf("cmd.HasOpts: foo = %t\n", cmd.HasOpt("foo"))
fmt.Printf("optCfgs[0].Name = %s\n", conn.OptCfgs()[0].Name)
fmt.Printf("options = %v\n", conn.Options())

Output:

err.IsOk = true
cmd.Name = app
cmd.Args = [bar]
cmd.HasOpts: foo = true
optCfgs[0].Name = foo
options = <nil>

func NewDaxSrcWithOptCfgs 

func NewDaxSrcWithOptCfgs(cfgs []cliargs.OptCfg) *DaxSrc

NewDaxSrcWithOptCfgs is the constructor function for cliargdax.DaxSrc struct that takes an array of instances of the cliargs.OptCfg struct.

Example 
os.Args = []string{"path/to/app", "--foo", "bar"}

base := sabi.NewDaxBase()
defer base.Close()

type MyOptions struct {
	Foo bool `optcfg:"foo"`
}
base.Uses("cliarg", cliargdax.NewDaxSrcForOptions(&MyOptions{}))

conn, err := sabi.GetDaxConn[cliargdax.DaxConn](base, "cliarg")
fmt.Printf("err.IsOk = %t\n", err.IsOk())

cmd := conn.Cmd()
fmt.Printf("cmd.Name = %s\n", cmd.Name)
fmt.Printf("cmd.Args = %v\n", cmd.Args())
fmt.Printf("cmd.HasOpts: foo = %t\n", cmd.HasOpt("foo"))

fmt.Printf("optCfgs[0].Name = %s\n", conn.OptCfgs()[0].Name)

options := conn.Options().(*MyOptions)
fmt.Printf("options.Foo = %v\n", options.Foo)

Output:

err.IsOk = true
cmd.Name = app
cmd.Args = [bar]
cmd.HasOpts: foo = true
optCfgs[0].Name = foo
options.Foo = true

func (*DaxSrc) Close 

func (ds *DaxSrc) Close()

Close is the one of the required methods for a struct that inherits sabi.DaxSrc. This method is empty and does nothing.

func (*DaxSrc) CreateDaxConn 

func (ds *DaxSrc) CreateDaxConn() (sabi.DaxConn, errs.Err)

CreateDaxConn is the one of the required methods for a struct that inherits sabi.DaxSrc. This method creates a new instance of cliargdax.DaxConn struct.

func (*DaxSrc) Setup 

func (ds *DaxSrc) Setup(ag sabi.AsyncGroup) errs.Err

Setup is the one of the required methods for a struct that inherits sabi.DaxSrc. This method parses command line arguments and sets the results of the parsing to this DaxSrc instance. If failing to parse, this method returns errs.Err instnace that holds an error instance from cliargs.Parse/ParseWith/ParseFor function as the error reason.

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.