goalfred

README

goalfred

goalfred is a helper package to create workflows for Alfredapp.

Get

go get -u github.com/BenchR267/goalfred/...

Usage

import "github.com/BenchR267/goalfred"

Construct your data like you want it to appear in the script filter output. You can then either use the given Item struct to add elements to the output or provide your custom types:

Using Item:

func main() {

	defer goalfred.Print()

	item := goalfred.Item {
			Title: "aTitle",
			Subtitle: "aSubtitle",
			Arg: "https://www.example.com",
	}
	item.Mod.Alt = &goalfred.ModContent {
			Arg: "https://www.google.de",
			Subtitle: "Open Google!",
  }

	goalfred.Add(item)
}

Using a custom type like Link:

type Link struct {
	Name  string
	Link1 string
	Link2 string
}

func (l Link) Item() goalfred.Item {
	item := goalfred.Item {
			Title: l.Name,
			Arg: l.Link1,
	}

	item.Mod.Cmd = &goalfred.ModContent {
			Arg: l.Link2,
			Subtitle: "Something special!",
  }
	return item
}

func main() {

	defer goalfred.Print()

	link := Link{
		Name: "Google",
		Link1: "https://www.google.com",
		Link2: "https://www.google.de/search?q=hello+world",
	}

	goalfred.Add(link)
}

Customization

Each Item has many properties, most of them are optional. To get more information about them, take a look at the official documentation at Alfred.

Complex Arguments

Sometimes it's necessary to output more than one parameter by the workflow. For example if you want to schedule a notification like alfred_dvb does. If an entry was selected there are multiple informations that should be outhanded. The first one is the time after which the notification should be triggered and the second one is the text for the notification. You could add a script that splits a given string into pieces, but with goalfred you can also add complex arguments that contain a query AND parameters. You can achieve this by doing the following:

item := goalfred.Item{
	Title: "a title",
	Subtitle: "a subtitle",
}
item.SetComplexArg(goalfred.ComplexArg{
	Arg: "A nice query that can be used as {query} in Alfred actions",
	Variables: map[string]interface{}{
		"time": 5,
		"output": "this text will replace {var:output} in Alfred actions!",
	},
})

As you can already see in the code, you can specify variables as well. You can use then the variables value by writing {var:VARIABLENAME} in an Alfred action. Very handy!

Workflow variables

Alfred added a new functionality in 3.2 which makes it possible to add variables to your script filter. To do this just set the variables via your Go script filter:

SetVariable("aKey1", 5)
SetVariable("aKey2", "aValue")

The variables are then exposed as environment variables to your following scripts.

Rerun

Sometimes you want to rerun your workflow after a given amount of time. Set this value with

Rerun(2)

before printing your output to Alfred. This will then rerun the workflow after the given amount of seconds.

CLI Tool

WARNING: Still in Alpha status!

goalfred also comes with a great cli tool to automate releases of your workflow. To install the tool, type in your terminal

go get github.com/BenchR267/goalfred/...

and run it by calling

$GOPATH/bin/goalfred release -v 1.0.0 DIRECTORY_PATH

with DIRECTORY_PATH replaced by the directory your files are located. Possible options are also -i and -g.

-i or --infoplist stands for bumping the version to the argument you specify at the -v option. -g or --git creates also a git tag and pushes that to your origin git remote.

License

This library is distributed under the MIT-style license found in the LICENSE file.

Documentation

Index

• func Add(item AlfredItem)
• func Arguments() []string
• func IsDebug() bool
• func Log(text string)
• func Normalize(input string) (output string, err error)
• func NormalizedArguments() (normalizedArgs []string, err error)
• func Print()
• func Rerun(seconds int)
• func SetVariable(key string, value interface{})
• type AlfredItem
• type ComplexArg
• type Icon
• type IconType
• type Item
  • func (i Item) Item() Item
  • func (i *Item) SetComplexArg(arg ComplexArg)
• type ItemType
• type ModContent
  • func (m *ModContent) SetComplexArg(arg ComplexArg)
• type ModElements

Functions

func Add

func Add(item AlfredItem)

Add adds the item to be ready to print

func Arguments

func Arguments() []string

Arguments just wrappes the call to os.Args for better readability

func IsDebug

func IsDebug() bool

IsDebug returns if the current environment has 'alfred_debug' set.

func Log

func Log(text string)

Log logs text to the debug panel. Only logs when IsDebug is true, so as not to interfere with the normal output.

func Normalize

func Normalize(input string) (output string, err error)

Normalize fixes problems with string encoding regarding the usage of special characters in Alfred. For more info on this topic, please refer to this thread: http://www.alfredforum.com/topic/2015-encoding-issue/

func NormalizedArguments

func NormalizedArguments() (normalizedArgs []string, err error)

NormalizedArguments re-normalizes the user arguments provided via Alfred. This isn't necessary for every workflow, specifically only when you're working with special characters. For more info on this topic, please refer to this thread: http://www.alfredforum.com/topic/2015-encoding-issue/ Arguments that couldn't get normalized are not part of the return value!

func Print

func Print()

Print prints out the saved items

func Rerun

func Rerun(seconds int)

Rerun sets the interval after how many seconds the workflow should run again

func SetVariable

func SetVariable(key string, value interface{})

SetVariable sets the value of a workflow wide variable which is passed as env var to the workflow

Types

type AlfredItem

type AlfredItem interface {
	Item() Item
}

AlfredItem defines that a struct is convertible to an Item

type ComplexArg

type ComplexArg struct {
	Arg       string                 `json:"arg,omitempty"`
	Variables map[string]interface{} `json:"variables,omitempty"`
}

ComplexArg gives you the opportunity to set variables as well that you can use later

type Icon

type Icon struct {
	Type IconType `json:"type,omitempty"`
	Path string   `json:"path,omitempty"`
}

Icon holds all information about an item's icon

type IconType

type IconType string

IconType describes the two possible values for the Type of an icon

const (
	// NoIconType makes Alfred load the file path itself
	NoIconType IconType = ""

	// FileIconType makes Alfred get the icon for the specified path
	FileIconType IconType = "fileicon"

	// FileTypeIconType makes Alfed get the icon of a specific file
	FileTypeIconType IconType = "filetype"
)

type Item

type Item struct {
	UID          string      `json:"uid,omitempty"`
	Title        string      `json:"title"`
	Subtitle     string      `json:"subtitle"`
	Arg          string      `json:"arg,omitempty"`
	Icon         *Icon       `json:"icon,omitempty"`
	Valid        *bool       `json:"valid,omitempty"`
	Autocomplete string      `json:"autocomplete,omitempty"`
	Type         ItemType    `json:"type,omitempty"`
	Mod          ModElements `json:"mods,omitempty"`
	Quicklook    string      `json:"quicklookurl,omitempty"`
}

Item stores informations about on item in the script filter A possible gotcha here is the `Valid` attribute, which is a pointer to a bool. This ensures it is whatever you set it and it gets included in the output if and only if you set it.

func (Item) Item

func (i Item) Item() Item

Item is an AlfredItem

func (*Item) SetComplexArg

func (i *Item) SetComplexArg(arg ComplexArg)

SetComplexArg sets the argument of the item to a more complex one that could contain variables as well

type ItemType

type ItemType string

ItemType describes the type of an Item

const (
	// NoItemType is the default item type, you could also leave it in the zero value state
	NoItemType ItemType = ""

	// FileItemType makes Alfred treat your result as a file on your system
	FileItemType ItemType = "file"

	// SkipCheckItemType makes Alfred skip this check as you are certain that the files you are returning exist
	SkipCheckItemType ItemType = "file:skipcheck"
)

type ModContent

type ModContent struct {
	Valid    bool   `json:"valid,omitempty"`
	Arg      string `json:"arg,omitempty"`
	Subtitle string `json:"subtitle,omitempty"`
}

ModContent holds all informations about a modifier of an Item

func (*ModContent) SetComplexArg

func (m *ModContent) SetComplexArg(arg ComplexArg)

SetComplexArg sets the argument of the item to a more complex one that could contain variables as well

type ModElements

type ModElements struct {
	Alt *ModContent `json:"alt,omitempty"`
	Cmd *ModContent `json:"cmd,omitempty"`
}

ModElements is a collection of the different modifiers for the item Alt will be visible when holding the alt-key Cmd will be visible when holding the cmd-key