github.com/clysto/awgo@v0.15.0/README.md (about) 1 2 <div align="center"> 3 <img src="./Icon.png" alt="AwGo Logo" title="AwGo Logo"> 4 </div> 5 6 AwGo — A Go library for Alfred workflows 7 ======================================== 8 9 [![Build Status][travis-icon]][travis-link] 10 [![Coverage Status][coveralls-icon]][coveralls-link] 11 [![Go Report Card][goreport-icon]][goreport-link] 12 [![GoDoc][godoc-icon]][godoc-link] 13 14 Full-featured library to build lightning-fast workflows in a jiffy. 15 16 Features 17 -------- 18 19 - Easy access to [Alfred and workflow settings][config]. 20 - Fluent API for generating [Alfred JSON feedback][feedback] for Script Filters. 21 - Support for all applicable Alfred features up to v3.6. 22 - [Fuzzy sorting/filtering][fuzzy] of results. 23 - [Simple, but powerful, API][cache-api] for [caching/saving workflow data][cache]. 24 - [Catches panics, logs stack trace and shows user an error message][run]. 25 - Workflow [update API][update] with built-in support for [GitHub releases][update-github]. 26 - [Pre-configured logging][logging] for easier debugging, with a rotated log file. 27 - ["Magic" queries/actions][magic] for simplified development and user support. 28 - macOS [system icons][icons]. 29 30 31 Installation & usage 32 -------------------- 33 34 Install AwGo with: 35 36 ```sh 37 go get -u github.com/deanishe/awgo 38 ``` 39 40 Typically, you'd call your program's main entry point via `Workflow.Run()`. 41 This way, the library will rescue any panic, log the stack trace and show 42 an error message to the user in Alfred. 43 44 program.go: 45 46 ```go 47 package main 48 49 // Package is called aw 50 import "github.com/deanishe/awgo" 51 52 // Workflow is the main API 53 var wf *aw.Workflow 54 55 func init() { 56 // Create a new Workflow using default settings. 57 // Critical settings are provided by Alfred via environment variables, 58 // so this *will* die in flames if not run in an Alfred-like environment. 59 wf = aw.New() 60 } 61 62 // Your workflow starts here 63 func run() { 64 // Add a "Script Filter" result 65 wf.NewItem("First result!") 66 // Send results to Alfred 67 wf.SendFeedback() 68 } 69 70 func main() { 71 // Wrap your entry point with Run() to catch and log panics and 72 // show an error in Alfred instead of silently dying 73 wf.Run(run) 74 } 75 ``` 76 77 In the Script Filter's Script box (Language = /bin/bash with input as 78 argv): 79 80 ```sh 81 ./program "$1" 82 ``` 83 84 85 Documentation 86 ------------- 87 88 Read the docs [on GoDoc][godoc]. 89 90 Check out the [example workflows][examples-code] ([docs][examples-docs]), which 91 show how to use AwGo. Use one as a template to get your own workflow up and 92 running quickly. 93 94 95 Running/testing 96 --------------- 97 98 The library, and therefore the unit tests, rely on being run in an Alfred-like 99 environment, as they pull configuration options from environment variables 100 (which are set by Alfred). 101 102 As such, you must `source` the `env.sh` script in the project root or run unit 103 tests via the `run-tests.sh` script (which also sets up an appropriate 104 environment before calling `go test`). 105 106 107 Licensing & thanks 108 ------------------ 109 110 This library is released under the [MIT licence][licence]. 111 112 The icon is based on the [Go Gopher][gopher] by [Renee French][renee]. 113 114 115 [alfred]: https://www.alfredapp.com/ 116 [licence]: ./LICENCE 117 [godoc]: https://godoc.org/github.com/deanishe/awgo 118 [gopher]: https://blog.golang.org/gopher 119 [renee]: http://reneefrench.blogspot.com 120 [config]: https://godoc.org/github.com/deanishe/awgo#Config 121 [feedback]: https://godoc.org/github.com/deanishe/awgo#Feedback.NewItem 122 [fuzzy]: https://godoc.org/github.com/deanishe/awgo/fuzzy 123 [cache]: https://godoc.org/github.com/deanishe/awgo#hdr-Saving_and_caching_data 124 [cache-api]: https://godoc.org/github.com/deanishe/awgo#Cache 125 [run]: https://godoc.org/github.com/deanishe/awgo#Run 126 [update]: https://godoc.org/github.com/deanishe/awgo/update 127 [update-github]: https://godoc.org/github.com/deanishe/awgo/update#GitHub 128 [logging]: https://godoc.org/github.com/deanishe/awgo#hdr-Logging 129 [magic]: https://godoc.org/github.com/deanishe/awgo#MagicAction 130 [icons]: https://godoc.org/github.com/deanishe/awgo#Icon 131 [examples-code]: https://github.com/deanishe/awgo/tree/master/_examples 132 [examples-docs]: https://godoc.org/github.com/deanishe/awgo/_examples 133 [travis-link]: https://travis-ci.org/deanishe/awgo 134 [travis-icon]: https://travis-ci.org/deanishe/awgo.svg?branch=master 135 [goreport-link]: https://goreportcard.com/report/github.com/deanishe/awgo 136 [goreport-icon]: https://goreportcard.com/badge/github.com/deanishe/awgo 137 [coveralls-icon]: https://coveralls.io/repos/github/deanishe/awgo/badge.svg?branch=master 138 [coveralls-link]: https://coveralls.io/github/deanishe/awgo?branch=master 139 [godoc-icon]: https://godoc.org/github.com/deanishe/awgo?status.svg 140 [godoc-link]: https://godoc.org/github.com/deanishe/awgo