gomate

README

Gomate

Gomate is a set of TextMate CLI tools for working with Go code. Inspired by syscrusher/golang.tmbundle.

Gomate embraces the Unix philosophy adopted by Textmate by utilizing simple CLI tool constructs, such as:

• Command line arguments to indicate desired action
• Sourcing environment variable for context of operation
• Reading input from STDIN and producing desired output on STDOUT

Additionally, Gomate is comprised of many smaller packages with dedicated functions to allow for maximum reuse outside the scope of Textmate. For example, you may want to use the note parsing package and build your own extension to a different tool (e.g. VSCode or VIM).

The modular design also encouraged the development of some dedicated CLI tools:

• notes - provided a path, will scan recursively and return all godoc notes in all packages
  • Installation: go get github.com/pokstad/gomate/notes/notes
  • Usage: $GOPATH/bin/notes [OPTIONS] PACKAGE_PATH

Install

To get the gomate CLI:

go get -u github.com/pokstad/gomate

Then, install the tool's dependencies:

$GOPATH/bin/gomate install

Usage

Until the bundle install is automated, the following needs to be done manually for each bundle command script:

References

To find references to the symbol under the cursor:

#!/bin/bash
gomate references

• Output: is set to Show in New Window
  • Format: is HTML

External dependencies: guru

Outline

To generate an outline of the current source code file:

#!/bin/bash
gomate outline

• Input: is set to Selection
  • Format is set to Text
• Output: is set to Show in New Window
  • Format: is HTML

Get Documentation

To view HTML documentation of the symbol under the cursor:

#!/bin/bash
gomate getdoc

• Input: is set to Document
  • Format is set to Text
• Output: is set to Show in New Window
  • Format: is HTML

External dependencies: gogetdoc

Notes

To view a list of gonotes in the current project:

#!/bin/bash
gomate notes

• Input: Nothing
• Ouput: Show in New Window
  • Format: HTML

Rename

To rename an identifier:

#!/bin/bash
gomate rename

• Input: Nothing
• Output: Discard

External dependencies: gorename

Roadmap

• Testing coverage and advanced options for individual test functions (similar to VSCode code lense)
• Reimplement all features of existing Textmate plugin syscrusher/golang.tmbundle
• Web service to support rich contexts that allow interactions via AJAX calls

Documentation

Index

• type CodeRef
  • func (cf CodeRef) String() string
  • func (cf CodeRef) URL() *url.URL
• type Cursor
  • func (c Cursor) RuneOffset() (int, error)
• type Drawer
• type Env
  • func LoadEnvironment() (env Env, err error)
  • func (e Env) GoBin(exe string) string
• type ExitCode
• type Scope

Types

type CodeRef

type CodeRef struct {
	AbsPath  string
	Line     uint
	Column   uint
	RelPath  string
	Filename string
	Excerpt  string
}

CodeRef is a reference to a specific piece of code in a textmate document

func (CodeRef) String

func (cf CodeRef) String() string

String returns the URL representation of a code ref

func (CodeRef) URL

func (cf CodeRef) URL() *url.URL

URL returns a textmate specific URL pointing to the code ref

type Cursor

type Cursor struct {
	Dir          string // directory of current doc (may be empty)
	Doc          string // filepath to document (may be empty)
	Line         int    // line number (starting at 1)
	Index        int    // index of line (starting at 1)
	Scope        Scope  // scope type specified by grammar
	Word         string // the word under the cursor (may be empty)
	SelectedText string // text currently highlighted by cursor (may be empty)
}

Cursor contains all information to determine where the UI cursor is currently pointing

func (Cursor) RuneOffset

func (c Cursor) RuneOffset() (int, error)

RuneOffset attemps to calculate the rune offset for the cursor in the specified document. An error may occur if the document does not exist OR if the desired offset is out of bounds of the provided file.

type Drawer

type Drawer struct {
	TopDir        string   // top level folder in project drawer
	Selected      []string // files and dirs currently selected
	SelectedFirst string   // first selected file (what determines first?)
}

Drawer represents the drawer state

type Env

type Env struct {
	Cursor Cursor // where is current caret/cursor pointing?
	Drawer Drawer // current state of project drawer?

	// remaining dynamic env vars
	BundleDir   string // the support folder of the bundle that ran the item
	SoftTabs    bool   // are soft tabs being used?
	SupportPath string // common textmate support items
	TabSize     int    // size of soft tabs

	// Static Environment Variables
	GoPath string // GOPATH variable
	Dialog string // Path to Textmate dialog helper app
}

Env represents all required data derived from textmate/system environment variables

func LoadEnvironment

func LoadEnvironment() (env Env, err error)

LoadEnvironment sources all environment variables or populates defaults

func (Env) GoBin

func (e Env) GoBin(exe string) string

GoBin returns the path to an executable in the $GOPATH/bin directory

type ExitCode

type ExitCode int

ExitCode is an enumeration of the different exit codes supported by Textmate. Note: exit codes are ignored if HTML output is being used Refer to the official docs: https://github.com/textmate/bundle-support.tmbundle/blob/master/Support/shared/lib/exit_codes.rb

const (
	// ExitDiscard will discard output
	ExitDiscard ExitCode = iota + 200
	// ExitReplaceText will replace the selected text with the output
	ExitReplaceText
	// ExitReplaceDocument will replace the entire document with the output
	ExitReplaceDocument
	// ExitInsertText will insert the output at the cursor location
	ExitInsertText
	// ExitInsertSnippet will insert the snippet at the cursor location
	ExitInsertSnippet
	// ExitShowHTML will render output as HTML in a separate window
	ExitShowHTML
	// ExitShowToolTip will show the output as a tool tip near the cursor
	ExitShowToolTip
	// ExitCreateNewDoc will create a new document with the output
	ExitCreateNewDoc
	// ExitInsertSnipNoIdent will insert the snippet at the cursor with no
	// additional indentation
	ExitInsertSnipNoIdent
)

type Scope

type Scope string

Scope refers to the type of symbol under the cursor as determined by the textmate grammer See http://blog.macromates.com/2005/introduction-to-scopes/ for more info

const (
	// ScopeNone is when we don't receive a scope from textmate
	ScopeNone Scope = ""
)