github.com/ChicK00o/awgo@v0.29.4/README.md (about) 1 2 <div align="center"> 3 <img src="https://raw.githubusercontent.com/deanishe/awgo/master/Icon.png" alt="AwGo Logo" title="AwGo Logo"> 4 </div> 5 6 7 # AwGo — A Go library for Alfred workflows # 8 9 [![Build Status][ghaction-badge]][ghaction-link] 10 [![Go Report Card][goreport-badge]][goreport-link] 11 [![Coverage Status][coveralls-badge]][coveralls-link] 12 [![Go Reference][godoc-badge]][godoc-link] 13 14 <!-- 15 [![Build Status][azure-badge]][azure-link] 16 [![Build Status][travis-badge]][travis-link] 17 [![Codacy Quality][codacy-badge-quality]][codacy-link] 18 [![Codacy coverage][codacy-badge-coverage]][codacy-link] 19 [![Codecov coverage][codecov-badge]][codecov-link] 20 --> 21 22 23 Full-featured library to build lightning-fast workflows in a jiffy. 24 25 - [Features](#features) 26 - [Installation & usage](#installation--usage) 27 - [Documentation](#documentation) 28 - [Requirements](#requirements) 29 - [Development](#development) 30 - [Licensing & thanks](#licensing--thanks) 31 32 33 ## Features ## 34 35 - Full support for Alfred 3 & 4 36 - Bi-directional interface to [workflow's config][config] 37 - Fluent API for generating [Script Filter JSON][feedback] 38 - [Fuzzy sorting/filtering][fuzzy] 39 - [Simple, powerful API][cache-api] for [caching/saving workflow data][cache] 40 - Keychain API to [securely store (and sync) sensitive data][keychain] 41 - Helpers to [easily run scripts and script code][scripts] 42 - Workflow [update API][update] with built-in support for [GitHub][update-github] & [Gitea][update-gitea] 43 - [Pre-configured logging][logging] for easier debugging, with a rotated log file 44 - [Catches panics, logs stack trace and shows user an error message][run] 45 - ["Magic" queries/actions][magic] for simplified development and user support 46 - macOS [system icons][icons] 47 48 49 ## Installation & usage ## 50 51 Install AwGo with: 52 53 ```sh 54 go get -u github.com/ChicK00o/awgo 55 ``` 56 57 Typically, you'd call your program's main entry point via `Workflow.Run()`. 58 This way, the library will rescue any panic, log the stack trace and show 59 an error message to the user in Alfred. 60 61 program.go: 62 63 ```go 64 package main 65 66 // Package is called aw 67 import "github.com/ChicK00o/awgo" 68 69 // Workflow is the main API 70 var wf *aw.Workflow 71 72 func init() { 73 // Create a new Workflow using default settings. 74 // Critical settings are provided by Alfred via environment variables, 75 // so this *will* die in flames if not run in an Alfred-like environment. 76 wf = aw.New() 77 } 78 79 // Your workflow starts here 80 func run() { 81 // Add a "Script Filter" result 82 wf.NewItem("First result!") 83 // Send results to Alfred 84 wf.SendFeedback() 85 } 86 87 func main() { 88 // Wrap your entry point with Run() to catch and log panics and 89 // show an error in Alfred instead of silently dying 90 wf.Run(run) 91 } 92 ``` 93 94 In the Script Filter's Script box (Language = /bin/bash with input as 95 argv): 96 97 ```sh 98 ./program "$1" 99 ``` 100 101 ## Documentation ## 102 103 Read the docs [on pkg.go.dev][godoc]. 104 105 Check out the [example workflows][examples-code] ([docs][examples-docs]), which 106 show how to use AwGo. Use one as a template to get your own workflow up and 107 running quickly. 108 109 110 ## Requirements ## 111 112 The library (and therefore the unit tests) rely on being run in a minimally 113 Alfred-like environment, as they pull configuration options from the environment 114 variables set by Alfred. 115 116 This means that if you want to run AwGo-based code outside Alfred, e.g. in your 117 shell, you must set at least the following environment variables to meaningful 118 values, or the library will panic: 119 120 - `alfred_workflow_bundleid` 121 - `alfred_workflow_cache` 122 - `alfred_workflow_data` 123 124 And if you're using the update API, also: 125 126 - `alfred_workflow_version` 127 - `alfred_version` (not needed for Alfred 4+) 128 129 130 ## Development ## 131 132 To create a sufficiently Alfred-like environment, you can `source` the `env.sh` 133 script in the project root or run unit tests via the `run-tests.sh` script 134 (which also sets up an appropriate environment before calling `go test`). 135 136 137 ## Licensing & thanks ## 138 139 This library is released under the [MIT licence][licence]. It was built with 140 [neovim][neovim] and [GoLand by JetBrains][jetbrains]. 141 142 The icon is based on the [Go Gopher][gopher] by [Renee French][renee]. 143 144 145 [alfred]: https://www.alfredapp.com/ 146 [licence]: ./LICENCE 147 [godoc]: https://pkg.go.dev/github.com/ChicK00o/awgo 148 [gopher]: https://blog.golang.org/gopher 149 [renee]: http://reneefrench.blogspot.com 150 [config]: https://pkg.go.dev/github.com/ChicK00o/awgo#Config 151 [feedback]: https://pkg.go.dev/github.com/ChicK00o/awgo#Feedback.NewItem 152 [fuzzy]: https://pkg.go.dev/github.com/ChicK00o/awgo/fuzzy 153 [cache]: https://pkg.go.dev/github.com/ChicK00o/awgo#hdr-Storing_data 154 [cache-api]: https://pkg.go.dev/github.com/ChicK00o/awgo#Cache 155 [run]: https://pkg.go.dev/github.com/ChicK00o/awgo#Run 156 [keychain]: https://pkg.go.dev/github.com/ChicK00o/awgo/keychain 157 [scripts]: https://pkg.go.dev/github.com/ChicK00o/awgo/util#hdr-Scripting 158 [update]: https://pkg.go.dev/github.com/ChicK00o/awgo/update 159 [update-github]: https://pkg.go.dev/github.com/ChicK00o/awgo/update#GitHub 160 [update-gitea]: https://pkg.go.dev/github.com/ChicK00o/awgo/update#Gitea 161 [logging]: https://pkg.go.dev/github.com/ChicK00o/awgo#hdr-Logging 162 [magic]: https://pkg.go.dev/github.com/ChicK00o/awgo#MagicAction 163 [icons]: https://pkg.go.dev/github.com/ChicK00o/awgo#Icon 164 [examples-code]: https://github.com/ChicK00o/awgo/tree/master/_examples 165 [examples-docs]: https://pkg.go.dev/github.com/ChicK00o/awgo/_examples 166 [jetbrains]: https://www.jetbrains.com/?from=deanishe/awgo 167 [neovim]: https://neovim.io/ 168 169 [godoc-badge]: https://pkg.go.dev/badge/github.com/ChicK00o/awgo.svg 170 [godoc-link]: https://pkg.go.dev/github.com/ChicK00o/awgo 171 [goreport-link]: https://goreportcard.com/report/github.com/ChicK00o/awgo 172 [goreport-badge]: https://goreportcard.com/badge/github.com/ChicK00o/awgo 173 [azure-badge]: https://img.shields.io/azure-devops/build/deanishe/6cd8e4fe-7366-4485-aea6-e9d75e7757b2/1 174 [azure-link]: https://dev.azure.com/deanishe/AwGo/_build 175 [ghaction-badge]: https://github.com/ChicK00o/awgo/workflows/CI/badge.svg 176 [ghaction-link]: https://github.com/ChicK00o/awgo/actions?query=workflow%3ACI 177 [coveralls-badge]: https://coveralls.io/repos/github/deanishe/awgo/badge.svg?branch=master&v3 178 [coveralls-link]: https://coveralls.io/github/deanishe/awgo?branch=master 179 180 <!-- 181 [coverage-badge]: https://img.shields.io/codacy/coverage/e785f7b0e830468da6fa2856d62e59ab?color=brightgreen 182 [codacy-link]: https://www.codacy.com/app/deanishe/awgo 183 [travis-badge]: https://img.shields.io/travis/deanishe/awgo 184 [travis-link]: https://travis-ci.org/deanishe/awgo 185 [codacy-badge-quality]: https://api.codacy.com/project/badge/Grade/e785f7b0e830468da6fa2856d62e59ab 186 [codacy-badge-coverage]: https://api.codacy.com/project/badge/Coverage/e785f7b0e830468da6fa2856d62e59ab 187 [travis-badge]: https://travis-ci.org/deanishe/awgo.svg?branch=master 188 [codecov-badge]: https://codecov.io/gh/deanishe/awgo/branch/master/graph/badge.svg 189 [codecov-link]: https://codecov.io/gh/deanishe/awgo 190 [coveralls-badge]: https://img.shields.io/coveralls/github/deanishe/awgo/master 191 [ghaction-badge]: https://img.shields.io/github/workflow/status/deanishe/awgo/CI 192 -->