building awesome cli apps in go

BUILDING AN AWESOME CLI APP IN GO

1

2

ASHLEY MAC

•Dev Advocate at Rackspace

•Go newbie

•Slightly sarcastic3

–Ashley Mac

“I have no idea what i’m doing”

4

SPF13

•Willfully Unemployed

•Builds Cool Things With Go AKA Gopher

•Irritatingly Specific5

–Steve

“I Kinda Know What I'm Doing”

6

MAKE SURE YOU HAVE GO INSTALLED

AND WORKING + AN EDITOR

7

UX OF CLI

8

HUMAN INTERFACE GUIDELINES

FOR CLIS9

UNIx PHILOSOPHY

10

KEN'S "UNIx PHILOSOPHY"11

UNIx PHILOSOPHY

•Simple

•Clear

•Composable

•Extensible

•Modular

•Small12

– Rob Pike

“Many UNIX programs do quite trivial things in isolation, but, combined with other programs, become general and

useful tools.” 13

– Doug McIlroy

“The manual page, which really used to be a manual page, is now a small volume,

with a thousand options” 14

POSIx + GNU

15

COMMANDS

16

WHAT ARE COMMANDS

?17

› ls

c:\dir

COMMANDS

18

› ls

› cp

› cat

› cd

list

copy

concatenate

change directory

ABBREVIATED

19

› ls

› cp

› cat

› cd

SHORT

20

Short

Clear&

› lsCONTExT

21

operates in current Directory

THE LANGUAGE OF COMMANDS

22

› lsHAS A LANGUAGE

23

List the contentsof the directory I'm in

› ls

› rm

› zip

› find

COMMANDS

24

Verbs

c:\dir

COMMANDS

25

Noun?

ARGS26

WHAT ARE ARGS?

27

› rm [file]

› cp [file] [newfile]

c:\copy [file] [newfile]

INPUT

28

> rm [file] ... [fileN]

MANY INPUTS

29

Arg0 Argn

> cp [file] [newfile]

ORDER MATTERS

30

From To

> cp [file] [newfile]

SEPARATED

31

Space separates

THE LANGUAGE OF ARGS

32

> cp [file] [newfile]

DIRECT OBJECT

33

Verb Noun Noun

> cp [file] [newfile]

IS PROUNCABLE

34

Copy this file to here

OPTIONS35

FLAGS36

› rm [options] [file]

c:\del [options] [file]

MODIFY ACTIONS

37

› rm -f badfile.txt

SEPARATORS

38

Space separates

› rm --force

PREFIxED

39

prefix

› rm -f

PREFIxED

40

prefix

c:\ del /F

PREFIxED

41

prefix

-f == --force

SHORT VS LONG

42

Common Options shortened

› rm -r -f rm -rf

STACKABLE

43

Short options stack

THE LANGUAGE OF FLAGS

44

› rm --force [file]

ADVERB

45

Verb Adverb Noun

› rm --force [file]

PRONOUNCEABLE

46

Forcefully remove this file

› rm --force [file]

PRONOUNCEABLE

47

remove this file with Force

› ls --color /home/spf13

FLAG INPUT

48

Verb Adverb Noun

› ls --color /home/spf13

PRONOUNCEABLE

49

Colorfully list my home directory

› ls -a

MODIFY BEHAVIOR

50

› ls -a

MODIFY BEHAVIOR

51

List all the things

ALL ISN'T AN ADVERB

52

ADVERBS ExPRESS•manner

•place

•time

•frequency

•degree

•level of certainty

•etc.53

ADVERBS ANSWER•How? •In what way?

•When?

•Where? •To what extent?

54

› ls -a

MODIFY BEHAVIOR

55

List completely

to what extent?

› ls --width=40

IMPUTABLE

56

Input

to what extent?

› ls --width 40

IMPUTABLE

57

Input

to what extent?

› ls --width 40

PREPOSITION

58

Verb Preposition Obj

› ls --width 40

PRONOUNCEABLE

59

list the directory with a width of 40 cols

PREP PHRASE = ADVERB•consists of a preposition and its

object

•acts as an adverb

•"Speaking at OSCON"60

BAD FLAG DESIGN

61

FLAGS AS ACTIONS

62

› tar -xcvf

FLAG = ACTION

63

› tar

First option must be a mode specifier:

-c Create -r Add/Replace -t List -u Update -x Extract

FLAG = ACTION

64

› zip

› unzip

BETTER

65

FLAGS WITH FLAGS

66

Extract: tar -x [options]

-k Keep existing files

-m Don't restore mod times

FLAGS HAVING SUB FLAGS

67

Create: tar -c [options]

-z, -j, -J, --lzma Compress archive with gzip/bzip2/xz/lzma

FLAGS HAVING SUB FLAGS

68

INCOMPATIBLE FLAGS

69

ls [options]

-S sort by file size

-t sort by modification time

-U do not sort

...

INCOMPATIBLE FLAGS

70

ls -StU INCOMPATIBLE FLAGS

71

What should this do?

> ls

--sort=[size,modtime,none]

BETTER

72

DOUBLE FLAGS

73

› git pull --stat --no-stat FLAG --NO-FLAG

74

› git pull --stat

› git pull --stat=false

BETTER

75

CLI APPS76

› httpd

› vi

› emacs

› git

CLI APPS

77

Noun

APPS

•Launch something

•Do more than one thing

•Collection of commands78

SUB COMMANDS

79

› svn add

› brew install

› npm search

› apt-get upgrade

› git clone

SUB COMMANDS

80

SUB COMMANDS•CLI apps do multiple things

•Apps are groups of commands

•(sub) Commands have flags & args

•All rules still apply81

› brew fetch -v hugo

ExPANDED RESOURCES

82

Cmd ArgApp Flag

› brew install hugo

NOUN

83

Verb ObjectNoun

› brew install hugo

PRONOUNCABLE

84

Brew, install hugo

› brew fetch -v hugo

PRONOUNCABLE

85

Verb ObjectNoun adVerb

› brew fetch -v hugo

PRONOUNCABLE

86

Brew, verbosely fetch hugo

GO INTRODUCTION

87

MY ExPERIENCE

88

GOPATH AND SETUP•You WILL store your code in a GitHub

user folder (example: $GOPATH/src/github.com/username/helloworld)

•This was a pain in the ass

•I was comfortable with /code /dev/ or /projects 89

GOPATH AND SETUP

•By Storing code on github, I was able to share my many problems

•Going from “I’m working on this” to “let’s collaborate”

90

GOPATH•The Go toolset uses an environment variable

called GOPATH to find Go source code.

•You can set GOPATH to anything you want, but things will be easier if it’s set in your home directory.

91

Windows:

c:\ setx GOPATH %USERPROFILE%

OS X:

❯ echo 'export GOPATH=$HOME\n' >> ~/.bash_profile

Close the terminal, reopen it, and type the following:

❯ echo $GOPATH

GO PATH

92

GOPATH AND SETUP

•Typing go get github.com/user/project will download and build a project.

93

EDITORS•No IDE needed - any text editor will do.

•helpful features like autocomplete and format & import on-save

•If you’re not sure what to use, I recommend Atom — It’s free, cross-platform, and easy to install. 94

PLUGINS•Atom: https://github.com/joefitzgerald/go-plus

•Vim: https://github.com/fatih/vim-go

•included in http://vim.spf13.com/

•IntelliJ: https://plugins.jetbrains.com/plugin/?id=5047

•Full list: https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins 95

YOU DON’T NEED A FRAMEWORK!

•The standard library has tons!

•Web server

•Templates

•Database

•etc.. 96

YOU DON’T NEED A FRAMEWORK!

•Many Packages work well together

•Very modular & Composable

97

STANDARD LIBRARYLet’s be honest, you don’t want to write everything from scratch so most programming depends on your ability to interface with existing libraries. i.e. packages. Here are a few core packages you should know about;

•Strings

•Input/Output (io/ioutil)

•Errors

•fmt

98

• Containers and Sort

• path/filepath

• HTTP (net/http)

• math/rand

GO99

STATICALLY TYPED

100

STRONGLY TYPED

101

COMPILED102

MEMORY MANAGED

103

POWERFUL CONCURRENCY

BAKED IN104

OPEN SOURCE

105

CROSS PLATFORM

106

LANGUAGE DESIGN

107

108

•Ken Thompson (B,C, Unix, UTF-8)

•Rob Pike (Unix, UTF-8)

•Robert Griesmier (Hotspot, JVM, V8)

MAJOR INFLUENCES

•C & derivatives

•Pascal & derivatives

•CSP109

IDEALS

•Expressibility •Edibility •Powerful

•Simple •Scalable

110

SPEC

•Java Spec : 670 pages

•YAML Spec : 84 pages

•Go Spec : 82 pages111

KEYWORDS•break

•default

•func

•interface

•select

•case

•defer

•go 112

•map

•struct

•chan

•else

•goto

•package

•switch

•const

•fallthrough

•if

•range

•type

•continue

•for

•import

•return

•var

BRACES

113

Fail

BRACES

Compile Eror

114

Compile Error

/tmp/sandbox826898458/main.go:6: syntax error: unexpected semicolon or newline before {

BRACES

What works

115

Works

VARIABLES

116

Fail

VARIABLES

117

Error

/tmp/sandbox473116179/main.go:6: one declared and not used /tmp/sandbox473116179/main.go:7: two declared and not used /tmp/sandbox473116179/main.go:8: three declared and not used

WHAT GO DOESN’T HAVE

118

CLASSES ( * SHOCKED

EXPRESSION *)119

OBJECTS120

COMPLExITY

121

TYPES122

SINGLE VALUE TYPES

123

NUMBERS

•Integers (numbers without a decimal)

•Floating-Point Numbers (numbers that contain a decimal)

• int, int8-64, uint, uint8-64, float32,64124

STRINGS•A string is a sequence of

characters

•Go strings are immutable

•Go strings are made up of individual bytes (Usually one for each character)

125

MULTI VALUE TYPES

126

type person struct { name string age int }

STRUCT

127

ARRAY

•An array is an ordered sequence of elements of a single type

•Fixed length

•Arrays are indexed starting from 0128

SLICE

•Segment of an array

•Dynamic length

•Can be used without thinking about array underneath

129

MAP•Unordered collection of key-value

pairs

•Similar to associative arrays, hash tables, and dictionaries

•Dynamic Length130

SOME OTHER TYPES

131

FUNCTION•Function is a type

•First class citizen in Go

•Can have multiple input values

•Can have multiple return values132

POINTERS•Reference a location in memory

where a value is stored

•Represented using '*'

•Memory location referenced using '&'133

DEFINE YOUR OWN TYPES

•Composed of other types

•Not aliases

134

METHOD

•Function defined on a type

135

TOOLING136

GO HELPThe Go toolset has many different commands and subcommands. You can pull up a list by typing:

go help

You now have everything you need to get started

137

GO FMT

•Formats your go code for you

•Awesome to do "on save"

•End of all stylistic debates138

GO TESTWriting code isn’t easy and humans make mistakes so testing is really important, luckily, Go includes a program that makes writing tests easier:

go test

Fun Fact: The Go compiler knows to ignore code in files ending with _test.go

139

CLOSING THOUGHTS

140

I THINK GO IS AWESOME

141

IT HAS STRONG OPINIONS

142

COMPILATION IS VERY FAST (USUALLY A

SECOND OR TWO)143

AWESOME COMMUNITY

144

RESOURCES•Getting Started, official golang page — https://golang.org/doc/

•Parse’s move from Ruby to Golang — http://blog.parse.com/learn/how-we-moved-our-api-from-ruby-to-go-and-saved-our-sanity/

•Tutorial — Creating a Wiki — https://golang.org/doc/articles/wiki/ (this was the first big tutorial that got me to build something useful, take this one slow to get a grasps on its concepts)

•Golang — Concurrency is not Parallelism (Rob Pike), this video I found super informative about go’s concurency and got me excited to keep coding in Golang — https://youtu.be/cN_DpYBzKso

145

LET'S BUILD AN APP

146

147

HTTP://WWW.SLIDESHARE.NET/SPF13

148

HTTPS://GITHUB.COM/SPF13/TRI

149

1. DESIGNING OUR APP

150

WHAT'S IN A NAME?

151

SHOCKING AMOUNT OF TODO APPS

152

LET'S MAKE A BUNCH MORE

153

I'M CALLING MINE "TRI"

154

FEATURES155

FEATURES•Add Todo

•List Todos

•Mark "done"

•Search/Filter

•Priorities

•Archive

•Edit

•Create Dates

•Due Dates

•Tags

•Projects

156

INTERFACE DESIGN

157

ADDING158

› tri add "Add Priorities"ADD

159

› tri add Add PrioritiesADD

160

› tri add "Add Priorities"

ADD

161

Verb ObjectNoun

› tri add \ "Add Multi Todo Support" \ "Consider usage behaviors"

ADD

162

PRIORITY163

› tri add -p1 "Add listing"

ADD WITH PRIORITY

164

› tri add -p1 "Add listing"

ADD WITH PRIORITY

165

Verb ObjectNoun adVerb

› tri add -p1 "Add listing"

PRONOUNCEABLE

166

Tri, add "Add listing" Todo with a pri of 1

› tri add "Add listing P:1"

ALTERNATE SYNTAx

167

CONSIDERATIONS•What priority system to use?

•Numeric

•Alpha

•High, Middle, Low

•What's the default priority? 168

MY TODO

•High, Middle, Low

•H=1, L=3, M/_=2

•Default is 2169

LISTING170

› tri ls

LISTING

171

› tri list

LISTING

172

› tri

LISTING

173

› tri list

(1) Add Listing

Consider usage behaviors

Add Multi Todo Support

Add Priorities

LISTING OUTPUT

174

› tri list

(1) Add Listing

Add Priorities

Add Multi Todo Support

Consider usage behaviors

LISTING OUTPUT

175

› tri list

(H) Add Listing

Consider usage behaviors

Add Priorities

(L) Add Multi Todo Support

LISTING OUTPUT

176

› tri list

(H) Add Listing

Consider usage behaviors

Add Priorities

(L) Add Multi Todo Support

LISTING OUTPUT

177

› tri list

1. (H) Add Listing

2. Consider usage behaviors

3. Add Priorities

4. (L) Add Multi Todo Support

LISTING OUTPUT

178

FILTERING179

› tri list done

TOKENS

180

› tri list -p1

FLAGS

181

› tri list -p1

› tri list --due June

› tri list --created 12/15

› tri list --done -p1

FILTER BY PROPERTY

182

› tri list -p2

2. Consider usage behaviors

3. Add Priorities

FILTER BY PRIORITY

183

› tri list "Add"

1. (H) Add Listing

3. Add Priorities

4. (L) Add Multi Todo Support

SEARCHING

184

› tri list "Add" "Pri"

3. Add Priorities

SEARCHING

185

UPDATING186

› tri list

1. (H) Add Listing

2. Consider usage behaviors

3. Add Priorities

4. (L) Add Multi Todo Support

LISTING OUTPUT

187

› tri done 2

COMPLETING

188

› tri edit 1 "Improve Listing"

EDITING

189

› tri edit 1 -p2

› tri edit 2 --due 05/13/15

› tri edit 3 --created 12/15

EDITING

190

› tri edit 1 -p2

› tri list -p2

› tri edit 3 --created 12/15

› tri list --created 12/15

CONSISTENCY

191

› tri edit 1 2 3 -p2

BATCH EDIT?

192

2. CREATING A PROJECT

193

COBRA194

•A CLI Command Framework

•A tool to generate CLI apps & commands

•Powers Kubernetes, Dropbox, Git Lfs, CoreOS, Docker, Delve ...

195

› go get -u \

github.com/spf13/cobra/cobra

GET & INSTALL COBRA

196

› cobra

Cobra is a Cli library for Go that empowers applications. This application is a tool to generate the needed files to quickly create a Cobra application.

Usage:

cobra [command]

Available Commands:

add Add a command to a Cobra Application

COBRA

197

COBRA APP

BUILDER198

› cobra init \ github.com/<handle>/tri \

-a "<Your Name>"

COBRA INIT

199

Replace with your url, project name & Name

› cobra init ...

Your Cobra application is ready at

/Users/spf13/gopath/src/github.com/spf13/tri

COBRA

200

› cd $GOPATH/src/github.com/<name>/tri

CD TO PROJECT

201

Replace with your url, project name & Name

› tree

.

├── LICENSE

├── cmd

│   └── root.go

└── main.go

LOOK AT YOUR PROJECT

202

› go build

› ./tri

A longer description that spans multiple lines and likely contains examples

and usage of using your application. For example...

BUILD & RUN IT

203

YOU'VE JUST CREATED YOUR

1ST GO APP204

IT'S ALL UPHILL FROM

HERE205

LET'S WRITE SOME CODE

206

OPEN THE PROJECT IN AN EDITOR

207

208

LiteIDE

209

HTTPS://SOURCEFORGE.NET/PROJECTS/LITEIDE/FILES/X29/ 210

WORKING WITH THE

ROOT211

package cmdimport ( "fmt" "os" "github.com/spf13/cobra" "github.com/spf13/viper")

CMD/ROOT.GO

212

package cmdimport ( "fmt" "os" "github.com/spf13/cobra" "github.com/spf13/viper")

CMD/ROOT.GO

213

Notice package name

Matches Dir

// This represents the base command when called without any subcommandsvar RootCmd = &cobra.Command{ Use: "tri", Short: "A brief description of your application", Long: `A longer description that spans multiple lines and likely ... application.`,}

CMD/ROOT.GO

214

// This represents the base command when called without any subcommandsvar RootCmd = &cobra.Command{ Use: "tri", Short: "Tri is a todo application", Long: `Tri will help you get more done in less time.It's designed to be as simple as possible to help you accomplish your goals.`,

}

CMD/ROOT.GO

215

var RootCmd = &cobra.Command{ Use: "tri",...

CMD/ROOT.GO

216

Package level variable & Exported

MAIN217

MAIN MAIN MAIN•Go programs are all about "main"

•main.go (convention)

•main package

•main()218

package main import "github.com/<yours>/tri/cmd" func main() { cmd.Execute()}

MAIN.GO

219

package main import "github.com/<yours>/tri/cmd"func main() { cmd.Execute()}

MAIN.GO

220

Package Name

package main import "github.com/<yours>/tri/cmd" func main() { cmd.Execute()}

MAIN.GO

221

Function Name

func Execute() { if err := RootCmd.Execute(); err != nil { fmt.Println(err) os.Exit(-1) }}

CMD/ROOT.GO

222

Package level variable

>go run main.go

Tri will help you get more done in less time.

It's designed to be as simple as possible to help you accomplish your goals.

RUN IT

223

3. CREATING OUR ADD COMMAND

224

ADD "ADD"

225

> cd $GOPATH/src/github.com/spf13/tri

CD TO PROJECT

226

Replace with your url, project name & Name

> cobra add add

add created at $GOPATH/src/github.com/spf13/tri/cmd/add.go

COBRA ADD ADD

227

> go run main.go add

add called

RUN "ADD"

228

Bill wants me to replace go run with

go build./tri

MAKE "ADD" ADD

229

package cmdCMD/ADD.GO

230

var addCmd = &cobra.Command{ Use: "add", Short: "A brief description of your command", Long: `A longer description that spans multiple lines and likely...`, Run: func(cmd *cobra.Command, args []string) { // TODO: Work your own magic here fmt.Println("add called") },}

CMD/ADD.GO

231

var addCmd = &cobra.Command{ Use: "add", Short: "Add a new todo", Long: `Add will create a new todo item to the list`, Run: func(cmd *cobra.Command, args []string) { // TODO: Work your own magic here fmt.Println("add called") },}

CMD/ADD.GO

232

func addRun(cmd *cobra.Command, args []string){

fmt.Println("add called")

}

CMD/ADD.GO

233

var addCmd = &cobra.Command{ Use: "add", Short: "Add a new todo", Long: `Add will create a new todo item to the list`, Run: addRun,}

CMD/ADD.GO

234

func addRun(cmd *cobra.Command, args []string) { for _, x := range args { fmt.Println(x) }}

CMD/ADD.GO

235

FOR x, Y := RANGE•Provides a way to iterate over an array,

slice, string, map, or channel.

•Like Foreach or Each in other languages

•x is index/key, y is value

•_ allows you to ignore naming variables236

func init() { RootCmd.AddCommand(addCmd)}

CMD/ADD.GO

237

INIT()•Special function

•Called after package variable declarations

•Called prior to main.main()

•Each package may have multiple init()

•init() order un-guaranteed238

> go run main.go add \

"one two" three

one two

three

RUNNING ADD

239

4. CREATING OUR DATA

MODEL240

CREATE A NEW

PACKAGE241

242

New Folder New File

package todo type Item struct { Text string }

TODO/TODO.GO

243

NAMED TYPES•Can be any known type (struct,

string, int, slice, a new type you’ve declared, etc)

•Methods can be declared on it

•Not an alias - Explicit type244

USING OUR NEW TYPE

245

import ( "fmt" "github.com/spf13/cobra" "github.com/<yourname>/tri/todo")

CMD/ADD.GO

246

Replace with yourS

func addRun(...) { items := []todo.Item{} for _, x := range args { items = append(items, todo.Item{Text:x}) } fmt.Println(items)}

CMD/ADD.GO

247

func addRun(...) { items := []todo.Item{} for _, x := range args { items = append(items, todo.Item{Text:x}) } fmt.Println(items)}

CMD/ADD.GO

248

APPEND

•Append adds new values to a slice

•Append will grow a slice as needed

249

func addRun(...) { items := []todo.Item{} for _, x := range args { items = append(items, todo.Item{Text:x}) } fmt.Println(items)}

CMD/ADD.GO

250

func addRun(...) { items := []todo.Item{} for _, x := range args { items = append(items, todo.Item{Text:x}) } fmt.Println(items)}