mamba

README

🌟 mamba: Go template for library modules

🔰 Introduction

This project is a template to aid in the startup of Go library module projects.

📚 Usage

🎀 Features

• unit testing with Ginkgo/Gomega
• implemented with 🐍 Cobra cli framework, assisted by 🐲 Cobrass
• i18n with go-i18n
• linting configuration and pre-commit hooks, (see: linting-golang).

🔨 Developer Info

By using this template, there is no need to use the cobra-cli to scaffold your application as this has been done already. It should be noted that the structure that is generated by the cobra-cli has been significantly changed in this template, mainly to remove use of the init() function and to minimise use of package level global variables. For a rationale, see go-without-package-scoped-variables.

📝 Checklist of required changes

The following is list of actions that must be performed before using this template. Most of the changes concern changing the name mamba to the name of the new application. As the template is instantiated from github, the new name will automatically replace the top level directory name, that being mamba.

➕ The following descriptions use owner name pandora and repo name maestro as an example. That is to say the client has instantiated mamba template into github at url github.com/pandora/maestro

🤖 Automated changes

Automated via automate-checklist.sh script. When the user instantiates the repo, a github actions workflow is executed which applies changes to the clients repo automatically. The following description describes the changes that are applied on the user's behalf and the workflow is automatically deleted. However, there are other changes that should be made. These compose the manual checklist and should be heeded by the user.

✅ Rename import statements

• rename import paths: global search and replace snivilised/mamba to pandora/maestro

✅ Identifiers

• change mambaTemplData: perform a refactor rename (Rename Symbol) to maestroTemplData

✅ Global search replace mamba to maestro

Will take care of the following required changes:

• change module name: update the module name inside the .mod file in the root directory
• change ApplicationName: modify to reflect the new application name. This application name is incorporated into the name of any translation files to be loaded.
• update BINARY_NAME: Inside Taskfile.yml, change the value of BINARY_NAME to the name of the client application.
• update github action workflows: change the name of the workflows in the .yaml files to replace mamba to Maestro (note the change of case, if this is important).

✅ Localisation/Internationalisation

• change the names of the translation files: eg change mamba.active.en-GB.json to maestro.active.en-GB.json

✅ Miscellaneous automated changes

• reset version files: this is optional because the release process automatically updates the version number according to the tag specified by the user, but will initially contain the version number which reflects the current value of mamba at the time the client project is instantiated.
• change SOURCE_ID: to "github.com/pandora/maestro"

🖐 Manual changes

The following documents manual changes required. Manual checklist:

☑️ Structural changes

• github actions workflow: If the client does not to use github actions workflow automation, then these files (ci-workflow, release-workflow, .goreleaser.yaml), should be deleted.

• rename the widget command: rename widget-cmd.go and its associated test widget_test.go to whatever is the first command to be implemented in the application. The widget command can serve as a template as to how to define a new command, without having to start from scratch. It will be easier for the user to modify an existing command, so just perform a case sensitive search and replace for widget/Widget and replace with Foo/foo where foo represents the new command to be created.

• review bootstrap.go: this will need to be modified to invoke creation of any custom commands. The execute method of bootstrap should be modified to invoke command builder. Refer to the widget command to see how this is done.

☑️ Github changes

Unfortunately, github doesn't copy over the template project's settings to the client project, so these changes must be made manually:

Under Protect matching branches

• Require a pull request before merging ✅ ENABLE
• Require linear history ✅ ENABLE
• Do not allow bypassing the above settings ✅ ENABLE

Of course, its up to the user what settings they use in their repo, these are just recommended as a matter of good practice.

☑️ Code coverage

• coveralls.io: add maestro project

☑️ Miscellaneous changes

• replace README content
• update email address in copyright statement: The root.go file contains a placeholder for an email address, update this comment accordingly.
• create .env file: Add any appropriate secrets to a newly created .env in the root directory and to enable the deploy task to work, define a DEPLOY_TO entry that defines where builds should be deployed to for testing
• install pre-commit hooks: just run pre-commit install
• update translation file: Inside Taskfile.yml, add support for loading any translations that the app will support. By default, it deploys a translation file for en-US so this needs to be updated as appropriate.

🌐 l10n Translations

This template has been setup to support localisation. The default language is en-GB with support for en-US. There is a translation file for en-US defined as src/i18n/deploy/mamba.active.en-US.json. This is the initial translation for en-US that should be deployed with the app.

Make sure that the go-i18n package has been installed so that it can be invoked as cli, see go-i18n for installation instructions.

To maintain localisation of the application, the user must take care to implement all steps to ensure translate-ability of all user facing messages. Whenever there is a need to add/change user facing messages including error messages, to maintain this state, the user must:

• define template struct (xxxTemplData) in src/i18n/messages.go and corresponding Message() method. All messages are defined here in the same location, simplifying the message extraction process as all extractable strings occur at the same place. Please see go-i18n for all translation/pluralisation options and other regional sensitive content.

For more detailed workflow instructions relating to i18n, please see i18n README

🧪 Quick Test

To check the app is working (as opposed to running the unit tests), build and deploy:

task tbd

(which performs a test, build then deploy)

NB: the deploy task has been set up for windows by default, but can be changed at will.

Check that the executable and the US language file maestro.active.en-US.json have both been deployed. Then invoke the widget command with something like

maestro widget -p "P?<date>" -t 30

Optionally, the user can also specify the directory flag:

maestro widget -p "P?<date>" -t 30 -d foo-bar.txt

... where foo-bar.txt should be replaced with a file that actually exists.

This assumes that the the project name is maestro, change as appropriate.

Since the widget command uses Cobrass option validation to check that the file specified exists, the app will fail if the file does not exist. This serves as an example of how to implement option validation with Cobrass.

Documentation

Index

• Variables
• type ChangedFlagsMap
• type ExternalThirdParty
• type KnownByCollection
• type ThirdPartyChangedFlags
• type ThirdPartyCommandLine
• type ThirdPartyFlagKnownBy
• type ThirdPartyFlagName
• type ThirdPartyOptionValue
• type ThirdPartyPositional
• type ThirdPartyPositionalArgs

Variables

var (
	// Evaluate merges the secondary command line with the specified flags.
	// The flags that occur in specified take precedence over those in
	// secondary. There is a slight complication caused by the fact that
	// a flag in the specified set may be in the secondary set but in the opposite
	// form; eg a flag may be in its short from in specified but in long form
	// in secondary. This is resolved by the knownBy set. The specified set
	// contains flags in their bare long form (bare as in without dash prefix).
	Evaluate = clif.Evaluate

	// Expand returns a slice of strings representing the positional arguments and
	// flags/options to be executed by the third party program. before and flags
	// are represented as a ThirdPartyCommandLine. This means that they can be
	// represented by any slice of strings. However, since before represents
	// positional args, those args are not expected to include any flags. Those
	// flags would be specified in the flags parameter. after is optional and
	// again represents further positional arguments.
	Expand = clif.Expand
)

Types

type ChangedFlagsMap

type ChangedFlagsMap = clif.ChangedFlagsMap

ChangedFlagsMap represents the set of third party flags presented by the user on the command line. (NB: Cobra does not currently have a mechanism to collect third party flags, by convention, anything that follows " -- "), therefore we need to collect and handle these flags/options explicitly, which is less than ideal. A difference between ChangedFlagsMap and ThirdPartyCommandLine is that switch flags have a true/false option value in ChangedFlagsMap but not in ThirdPartyCommandLine.

type ExternalThirdParty

type ExternalThirdParty = clif.ExternalThirdParty

ExternalThirdParty base struct for cli applications using the entry paradigm that need to delegate an invocation to an external third party command.

type KnownByCollection

type KnownByCollection = clif.KnownByCollection

KnownByCollection collection maps a full flag name to the short name it is also known by. If a flag does not have a short name, it should be mapped to the empty string.

type ThirdPartyChangedFlags

type ThirdPartyChangedFlags = clif.ThirdPartyChangedFlags

ThirdPartyChangedFlags (see ChangedFlagsMap)

type ThirdPartyCommandLine

type ThirdPartyCommandLine = clif.ThirdPartyCommandLine

ThirdPartyCommandLine represents the collection of flags used to invoke a third party command. This collection represents the raw flags used for the invocation in the order required by the third party command. It also means that this collection contains the leading --/- not just the names of the flags and options. For example, to invoke the magick command we may want to compose this collection with: magick --strip --interlace plane --gaussian-blur 0.05 and in this case, the list would be defined as a string slice: []string{"--strip", "--interlace", "plane", "--gaussian-blur", "0.05"}

type ThirdPartyFlagKnownBy

type ThirdPartyFlagKnownBy = clif.ThirdPartyFlagsKnownBy

ThirdPartyFlagKnownBy (see KnownByCollection).

type ThirdPartyFlagName

type ThirdPartyFlagName = clif.ThirdPartyFlagName

ThirdPartyFlagName raw name of a flag, ie without the leading --/-

type ThirdPartyOptionValue

type ThirdPartyOptionValue = clif.ThirdPartyOptionValue

ThirdPartyOptionValue the string value of an option. Since this option is being delegated to a third party command, it does not have to be of a particular native go type and can be composed from a go type using the value's String() method.

type ThirdPartyPositional

type ThirdPartyPositional = clif.ThirdPartyPositional

ThirdPartyPositional represents a positional argument

type ThirdPartyPositionalArgs

type ThirdPartyPositionalArgs = clif.ThirdPartyPositionalArgs

ThirdPartyPositionalArgs represents a collection of third party positional arguments.