🦄 arcadia: Go template for Cobra based cli applications

🔰 Introduction

This project is a template to aid in the startup of Go cli applications.

📚 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 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 Arcadia 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 arcadia.

• github actions workflow: If the client application needs to use github actions for continuous integration, then the name of the workflow needs to be changed. If not, then the workflow file should be deleted

• remove the dummy code: widget-cmd.go, greeting.go and its associated test greeting_test.go (but only do this once new valid tests are ready to replace it, to avoid references being removed after go mod tidy)

• replace bootstrap testcase: There is a test case which by default is set to invoke the widget command. When the user is ready to remove this command, then the corresponding test case should be modified to invoke another command with appropriate parameters. This test case is there to ensure that the bootstrapping process works, as opposed to checking the validity of the command itself.

• change ApplicationName: modify to reflect the new application name. This application name is incorporated into the name of any translation files to be loaded.

• replace README content

• 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.

• update BINARY_NAME: Inside Taskfile.yml, change the value of BINARY_NAME to the name of the client application.

• 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.

• 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

• update message id: This package supports i18n and as part of that defines messages that need to be translated. The user needs to update the message ids of defined messages in messages.go, which by default contain arcadia as part of the id.

🌐 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/internal/l10n/out/arcadia.active.en-US.json.

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/internal/l10n/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.
• define a corresponding helper function in src/internal/translate/messages.go. These helper functions are the ones that the rest of the application will use in order to generate region sensitive user facing string content.
• cd to the l10n at src/internal/l10n/
• run goi18n extract -format json, this will create an updated active.en.json file
• run goi18n merge -outdir out -format json active.en.json translate.en-US.json
• rename out/active.en-US.json to out/arcadia.active.en-US.json. The name arcadia should be changed to the name of the new app (which should correspond with ApplicationName defined in src/app/command/root-cmd.go).

The file out/arcadia.active.en-US.json is the translation file that will be deployed with the executable. Of course, if you want to use a config file format other than json, then there will be a little more work to do, but is fairly straight forward.

🧪 Quick Test

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

task b

task d

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 arcadia.active.en-US.json have both been deployed. Then invoke the widget command with something like

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

Optionally, the user can also specify the directory flag:

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

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

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.