github.com/clysto/awgo@v0.15.0/doc.go (about) 1 // 2 // Copyright (c) 2018 Dean Jackson <deanishe@deanishe.net> 3 // 4 // MIT Licence. See http://opensource.org/licenses/MIT 5 // 6 // Created on 2018-02-10 7 // 8 9 /* 10 11 Package aw is a utility library/framework for Alfred 3 workflows 12 https://www.alfredapp.com/ 13 14 It provides APIs for interacting with Alfred (e.g. Script Filter feedback) and 15 the workflow environment (variables, caches, settings). 16 17 NOTE: AwGo is currently in development. The API *will* change and should 18 not be considered stable until v1.0. Until then, vendoring AwGo (e.g. 19 with dep or vgo) is strongly recommended. 20 21 22 Links 23 24 Docs: https://godoc.org/github.com/deanishe/awgo 25 26 Source: https://github.com/deanishe/awgo 27 28 Issues: https://github.com/deanishe/awgo/issues 29 30 Licence: https://github.com/deanishe/awgo/blob/master/LICENCE 31 32 Be sure to also check out the _examples/ subdirectory, which contains 33 some simple, but complete, workflows that demonstrate the features 34 of AwGo and useful workflow idioms. 35 36 37 Features 38 39 As of AwGo 0.14, all applicable features of Alfred 3.6 are supported. 40 41 The main features are: 42 43 - Simple access to workflow settings. 44 - Fluent API for generating Alfred JSON. 45 - Fuzzy filtering. 46 - Simple, but powerful, API for caching/saving workflow data. 47 - Run scripts and script code. 48 - Call Alfred's AppleScript API from Go. 49 - Read and write workflow settings from info.plist. 50 - Workflow update API with built-in support for GitHub releases. 51 - Pre-configured logging for easier debugging, with a rotated log file. 52 - Catches panics, logs stack trace and shows user an error message. 53 - "Magic" queries/actions for simplified development and user support. 54 - Some default icons based on macOS system icons. 55 56 57 Usage 58 59 Typically, you'd call your program's main entry point via Run(). This way, the 60 library will rescue any panic, log the stack trace and show an error message to 61 the user in Alfred. 62 63 // script_filter.go 64 65 package main 66 67 // Import name is "aw" 68 import "github.com/deanishe/awgo" 69 70 // aw.Workflow is the main API 71 var wf *aw.Workflow 72 73 func init() { 74 // Create a new *Workflow using default configuration 75 // (workflow settings are read from the environment variables 76 // set by Alfred) 77 wf = aw.New() 78 } 79 80 func main() { 81 // Wrap your entry point with Run() to catch and log panics and 82 // show an error in Alfred instead of silently dying 83 wf.Run(run) 84 } 85 86 func run() { 87 // Create a new item 88 wf.NewItem("Hello World!") 89 // And send the results to Alfred 90 wf.SendFeedback() 91 } 92 93 94 In the Script box (Language = "/bin/bash"): 95 96 ./script_filter 97 98 99 Script Filters 100 101 To generate results for Alfred to show in a Script Filter, use the feedback 102 API of Workflow: 103 104 // Create new items 105 NewItem() 106 NewFileItem() 107 NewWarningItem() 108 109 // Sorting/filtering results 110 Filter() 111 112 // Send feedback to Alfred 113 SendFeedback() 114 115 // Warning/error calls that drop all other Items on the floor 116 // and send feedback immediately 117 Warn() 118 WarnEmpty() 119 Fatal() // exits program 120 Fatalf() // exits program 121 FatalError() // exits program 122 123 You can set workflow variables (via feedback) with Workflow.Var, Item.Var 124 and Modifier.Var. 125 126 See Workflow.SendFeedback for more documentation. 127 128 129 Run Script actions 130 131 Alfred requires a different JSON format if you wish to set workflow variables. 132 133 Use the ArgVars (named for its equivalent element in Alfred) struct to 134 generate output from Run Script actions. 135 136 Be sure to set TextErrors to true to prevent Workflow from generating 137 Alfred JSON if it catches a panic: 138 139 wf.Configure(TextErrors(true)) 140 141 See ArgVars for more information. 142 143 144 Configuration 145 146 New() creates a *Workflow using the default values and workflow settings 147 read from environment variables set by Alfred. 148 149 You can change defaults by passing one or more Options to New(). If 150 you do not want to use Alfred's environment variables, or they aren't set 151 (i.e. you're not running the code in Alfred), you must pass an Env as 152 the first Option to New() using CustomEnv(). 153 154 A Workflow can be re-configured later using its Configure() method. 155 156 Check out the _examples/ subdirectory for some simple, but complete, workflows 157 which you can copy to get started. 158 159 See the documentation for Option for more information on configuring a Workflow. 160 161 162 Fuzzy filtering 163 164 AwGo can filter Script Filter feedback using a Sublime Text-like fuzzy 165 matching algorithm. 166 167 Workflow.Filter() sorts feedback Items against the provided query, removing 168 those that do not match. 169 170 Sorting is performed by subpackage fuzzy via the fuzzy.Sortable interface. 171 172 See _examples/fuzzy for a basic demonstration. 173 174 See _examples/bookmarks for a demonstration of implementing fuzzy.Sortable on 175 your own structs and customising the fuzzy sort settings. 176 177 178 Logging 179 180 AwGo automatically configures the default log package to write to STDERR 181 (Alfred's debugger) and a log file in the workflow's cache directory. 182 183 The log file is necessary because background processes aren't connected 184 to Alfred, so their output is only visible in the log. It is rotated when 185 it exceeds 1 MiB in size. One previous log is kept. 186 187 AwGo detects when Alfred's debugger is open (Workflow.Debug() returns true) 188 and in this case prepends filename:linenumber: to log messages. 189 190 191 Workflow settings 192 193 The Config struct (which is included in Workflow as Workflow.Config) provides an 194 interface to the workflow's settings from the Workflow Environment Variables panel. 195 https://www.alfredapp.com/help/workflows/advanced/variables/#environment 196 197 Alfred exports these settings as environment variables, and you can read them 198 ad-hoc with the Config.Get*() methods, and save values back to Alfred with 199 Config.Set(). 200 201 Using Config.To() and Config.From(), you can "bind" your own structs to the 202 settings in Alfred: 203 204 // Options will be populated from workflow/environment variables 205 type Options struct { 206 Server string `env:"HOSTNAME"` 207 Port int // use default: PORT 208 User string `env:"USERNAME"` 209 Password string `env:"-"` // ignore 210 } 211 212 cfg := NewConfig() 213 opts := &Options{} 214 215 // Populate Config's fields from the corresponding environment variables. 216 if err := cfg.To(opts); err != nil { 217 // handle error 218 } 219 220 And to save a struct's fields to the workflow's settings in Alfred: 221 222 // Defaults 223 opts = &Options{ 224 Server: "localhost", 225 Port: 6000, 226 } 227 228 // Save Options to Alfred 229 if err := cfg.From(opts); err != nil { 230 // handle error 231 } 232 233 See the documentation for Config.To and Config.From for more information, 234 and _examples/settings for a demo workflow based on the API. 235 236 237 Alfred actions 238 239 The Alfred struct provides methods for the rest of Alfred's AppleScript 240 API. Amongst other things, you can use it to tell Alfred to open, to search 241 for a query, or to browse/action files & directories. 242 243 See documentation of the Alfred struct for more information. 244 245 246 Storing data 247 248 AwGo provides a basic, but useful, API for loading and saving data. 249 In addition to reading/writing bytes and marshalling/unmarshalling to/from 250 JSON, the API can auto-refresh expired cache data. 251 252 See Cache and Session for the API documentation. 253 254 Workflow has three caches tied to different directories: 255 256 Workflow.Data // Cache pointing to workflow's data directory 257 Workflow.Cache // Cache pointing to workflow's cache directory 258 Workflow.Session // Session pointing to cache directory tied to session ID 259 260 These all share the same API. The difference is in when the data go away. 261 262 Data saved with Session are deleted after the user closes Alfred or starts 263 using a different workflow. The Cache directory is in a system cache 264 directory, so may be deleted by the system or "System Maintenance" tools. 265 266 The Data directory lives with Alfred's application data and would not 267 normally be deleted. 268 269 Scripts and background jobs 270 271 Subpackage util provides several functions for running script files and 272 snippets of AppleScript/JavaScript code. See util for documentation and 273 examples. 274 275 AwGo offers a simple API to start/stop background processes via Workflow's 276 RunInBackground(), IsRunning() and Kill() methods. This is useful for 277 running checks for updates and other jobs that hit the network or take a 278 significant amount of time to complete, allowing you to keep your Script 279 Filters extremely responsive. 280 281 See _examples/update and _examples/workflows for demonstrations of this API. 282 283 */ 284 package aw