Golang Example Documentation

Go has been gaining a lot of popularity recently. With a lot of the success stories centered on the performance gains switching from other languages. For me a lot of the smaller features, that shows an attention to detail, which makes it enjoyable to code in. These details are also what will help the Golang community grow as well. One of these details is the built in documentation into the language.

There is a built in go doc command with the language where you can view your package documentation locally by running an http server to serve your docs. GoDoc is the main hosting for open source packages that will build docs for your package by doing a go get and generating docs. Locally you can run go doc from your package to display the docs in your terminal.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
$ cd $GOPATH/src/github.com/mtchavez/go-statsite/statsite
$ go doc
PACKAGE DOCUMENTATION

package statsite
    import "github.com/mtchavez/go-statsite/statsite"



VARIABLES

var MTypes []string = []string{
    "kv",
    "g",
    "ms",
    "c",
    "s",
}


TYPES

type Client struct {
    Conn net.Conn
    // contains filtered or unexported fields
}


func NewClient(addr string) (client *Client, err error)


func (c *Client) Emit(m Messenger) (bool, error)

func (c *Client) Emitter(msg string) (ok bool, err error)
...

Or you can view all the packages in your $GOSRC directory as well as the standard library code in your browser by running godoc -http=:6060. Then visit localhost:6060 in your browser. This looks the same as golang.org you may notice. Click on Packages and find the package you are looking for. This all comes built into the language itself.

If you have spent any time using go, browsed the standard library docs, used an open source go project you may have notice a Examples in docs. These examples are one of the details I mentioned that add to the language and help grow a community. Here is an example of the built in time package examples. The novel thing about this is it is just the built in examples from the Go source that get generated by go doc from the language itself. There is no extra documentation package or custom manages site.

So you have an open source project, or some internal go project, that you want to make life easier for others to pick up and understand. Lets write an example for them to understand how to use your package. Lets say you have a fibonacci number generator package. And you want to show someone how to use it with an example. Lets add a $GOPATH/src/fib directory with a fib.go main package with the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
package fib

import (
  "fmt"
  "os"
  "strconv"
)

func fib(n int) int {
  if n < 2 {
    return n
  }
  return fib(n-1) + fib(n-2)
}

Since we’ll be expecting others to use our package we’ll want to test it works as well as document how to use it. With examples we can do both in one shot. In our same $GOPATH/src/fib directory create a fib_test.go file. Lets add our example test.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
package fib

import (
  "fmt"
)

func Example() {
  var output int
  output = fib(10)
  fmt.Printf("Fibonacci of %v is %v\n", 10, output)
  output = fib(20)
  fmt.Printf("Fibonacci of %v is %v\n", 20, output)
  // Output:
  // Fibonnacci of 10 is 55
  // Fibonnacci of 20 is 6765
}

Now from your fib/ directory run go test and you should see some similar output:

1
2
3
$ go test
PASS
ok    fib 0.023s

This allowed us to both test our fibonacci package and show someone else an example how to use it. If the output changed or we broke our package our tests should fail as well.

1
2
3
4
5
6
7
8
9
10
11
$ go test
--- FAIL: Example (80.68us)
got:
Fibonacci of 10 is 55
Fibonacci of 20 is 6765
want:
Fibonacci of 10 is 55
Fibonacci of 20 is 55
FAIL
exit status 1
FAIL  fib 0.018s

Simple enough. What if you have a struct where you are calling a function off of and want to show how one would use the function. The principal is the same except we change our Example() function name in our test. If we change our fib.go to this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
package fib

import (
  "fmt"
  "os"
  "strconv"
)

type FibStruct struct {
  num    int
  result int
}

func fib(n int) int {
  if n < 2 {
    return n
  }
  return fib(n-1) + fib(n-2)
}

func (f *FibStruct) Calculate(num int) {
  f.num = num
  f.result = fib(num)
}

Then we can add an example on how to use our new Calculate() method in fib_test.go.

1
2
3
4
5
6
7
8
9
10
11
func ExampleFibStruct_Calculate() {
  f := FibStruct{}
  f.Calculate(10)
  fmt.Printf("Fibonacci of %v is %v\n", 10, f.result)

  f.Calculate(20)
  fmt.Printf("Fibonacci of %v is %v\n", 20, f.result)
  // Output:
  // Fibonacci of 10 is 55
  // Fibonacci of 20 is 6765
}

Running the tests again with go test should show everything passing. Last part to this is viewing your examples via go doc or on GoDoc. You can view this example at fib-go-example.

Go Timed Function Wrapper

Some times it is useful to see how long certain functions or group of lines take to run. If you are using something like statsite with Graphite exposing the time code takes to execute can be extremely insightful. I came up with a quick, and proably dirty, way to go about this using Go. Below is an example of wrapping functions to see how long they take. You can go over to Go Playground and run this example here to get a feel for what it does.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
package main

import (
  "fmt"
  "time"
)

type wrapped func()
type wrappedReturn func() interface{}

func Timed(fn wrapped, key string) {
  start := time.Now().Unix()
  fn()
  end := time.Now().Unix()
  fmt.Printf("Time: %d, Key: %s\n", end-start, key)
}

func TimedReturn(fn wrappedReturn, key string) interface{} {
  start := time.Now().Unix()
  resp := fn()
  end := time.Now().Unix()
  fmt.Printf("Time: %d, Key: %s]n", end-start, key)
  return resp
}

func main() {
  fn := func() {
    fmt.Println("Hello from wrapped function!")
    time.Sleep(time.Duration(1) * time.Second)
  }
  Timed(fn, "go.playground")

  fn2 := func() interface{} {
    fmt.Println("Hello from wrapped function with return!")
    time.Sleep(time.Duration(2) * time.Second)
    return []int{3}
  }
  returned := TimedReturn(fn2, "go.playground")
  fmt.Println("TimedReturn got:", returned.([]int))
}

Golang Implement Version Flag

So you’ve built your first service using Go and have it deployed out into your production environment. With cross compiling built into Go it’s easy and almost trivial to build a new binary of your code and deploy updates. But what happens when you need to know what version of your code is where or how can you easily verify your new binary was deployed.

There is a built in library in Go that handles flag parsing, the flag package. Using the flag package is straight forward and allows us to use flags to pass to our binary to print a version out.

First lets start with a main package that imports the flag package.

1
2
3
4
5
6
7
8
9
10
11
package main

import (
    "flag"
    "fmt"
)

func main() {
    flag.Parse()
    fmt.Println("Hello from main()")
}

If you have the file in your $GOROOT as main.go then run go build main.go and after running ./main you should see:

1
2
$ ./main
Hello from main()

So what did the flag.Parse() line do for us? Well it actually looked to parse any flags passed to the program. Since we did not pass anything it does not have to do any work here. Now lets add a version flag to parse so we can print the version of our program.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
package main

import (
    "flag"
    "fmt"
    "os"
)

const AppVersion = "1.0.0 beta"

func main() {
    version := flag.Bool("v", false, "prints current roxy version")
    flag.Parse()
    if *version {
      fmt.Println(AppVersion)
      os.Exit(0)
    }
    fmt.Println("Hello from main()")
}

We first start by adding a definition of our version flag. It will be a boolean flag with a name of v, a default of false and a description of what our flag means. Next we call flag.Parse() to look for any flags passed into our program. After parsing our version variable will have a value if we passed a -v to our program when running it. Run your program again, this time passing in our -v flag, and you should see the version string printed out and the program exist.

Some things to try out:

  1. What happens if you don’t pass in the -v flag?
  2. What is the difference if you change the default value for the flag from false to true?
  3. If you pass a flag other than -v what is the output of the program?

Go Current Directory of File

I recently needed to get the current file absolute path from a go file. You first need to get the runtime package which is a part of Go

1
import "runtime"

Next you can use the Caller method and capture the filename. We need to give this function a 1 to tell it to skip up a caller. You can read more about the function here

1
_, filename, _, ok := runtime.Caller(1)

The filename will be the path up to the current directory of the file that calls this function. The ok is to check if the function call was able to find the information requested.

So in practice if you wanted to get a config file up a directory and in a config directory you could do the following

1
filepath := path.Join(path.Dir(filename), "../config/settings.toml")

RubyMotion Threads

Should you need to perform some background tasks in your Ruby Motion app try the following:

1
2
3
4
5
6
7
8
# Call your 'background_method'
def some_method
  self.performSelectorInBackground('background_method:', withObject:nil)
end

def background_method
  print 'Background Method Called!'
end

It is as easy as that. If you need even more flexibility and find yourself wanting to give your background method something to work with you can pass objects to it instead of passing nil to withObject

1
2
3
4
5
6
7
8
9
# Use withObject to pass objects into background_method
def some_method
  details = {'username' => 'Chavez', 'email' => 'chavez@me.com' }
  self.performSelectorInBackground('background_method:', withObject:details)
end

def background_method(details)
  print "My details #{details}"
end

For other methods check the Apple docs

RubyMotion Custom Fonts

In your Rakefile add your font in the app setup.

1
2
3
4
Motion::Project::App.setup do |app|
  # App Settings
  app.fonts = ['st-marie.ttf']
end

Make sure your st-marie.ttf is in your resources directory

To use in your app do the following

1
my_font = UIFont.fontWithName 'St Marie', size: 32

To find your font family name

1
UIFont.familyNames.sort # Should contain 'St Marie'

To find the font names for a family name

1
2
# Returns array of font names for 'St Marie'
UIFont.fontNamesForFamilyName 'St Marie'