doc.go

// Copyright (c) 2018 Dean Jackson <deanishe@deanishe.net>
// MIT Licence - http://opensource.org/licenses/MIT

/*
Package aw is a "plug-and-play" workflow development library/framework for Alfred 3 & 4
(https://www.alfredapp.com/). It requires Go 1.13 or later.

It provides everything you need to create a polished and blazing-fast Alfred
frontend for your project.


Features

As of AwGo 0.26, all applicable features of Alfred 4.1 are supported.

The main features are:

	- Full support for Alfred 3 & 4
	- Bi-directional interface to workflow's configuration
	- Fluent API for generating Script Filter JSON
	- Fuzzy filtering
	- Simple, powerful API for caching/saving workflow data
	- Keychain API to securely store (and sync) sensitive data
	- API to call Alfred's AppleScript methods from Go code
	- Helpers to easily run scripts and script code
	- Workflow update API with built-in support for GitHub & Gitea
	- Pre-configured logging for easier debugging, with a rotating log file
	- Catches panics, logs stack trace and shows user an error message
	- "Magic" queries/actions for simplified development and user support
	- Some default icons based on macOS system icons


Usage

AwGo is an opinionated framework that expects to be used in a certain way in
order to eliminate boilerplate. It *will* panic if not run in a valid,
minimally Alfred-like environment. At a minimum the following environment
variables should be set to meaningful values:

	// Absolutely required. No ifs or buts.
	alfred_workflow_bundleid

	// Cache & data dirs can be set to anything, but for best
	// results, point them at the same directories as Alfred uses
	// Alfred 3:  ~/Library/Caches/com.runningwithcrayons.Alfred-3/Workflow Data/<bundle ID>/
	// Alfred 4+: ~/Library/Caches/com.runningwithcrayons.Alfred/Workflow Data/<bundle ID>/
	alfred_workflow_cache

	// Alfred 3:  ~/Library/Application Support/Alfred 3/Workflow Data/<bundle ID>/
	// Alfred 4+: ~/Library/Application Support/Alfred/Workflow Data/<bundle ID>/
	alfred_workflow_data

	// If you're using the Updater API, a semantic-ish workflow version
	// must be set otherwise the Updater will panic
	alfred_workflow_version

	// If you're using the Alfred API and running Alfred 3, you need to
	// set `alfred_version` as AwGo defaults to calling Alfred 4+
	alfred_version=3


NOTE: AwGo is currently in development. The API *will* change and should
not be considered stable until v1.0. Until then, be sure to pin a version
using go modules or similar.

Be sure to also check out the _examples/ subdirectory, which contains
some simple, but complete, workflows that demonstrate the features
of AwGo and useful workflow idioms.

Typically, you'd call your program's main entry point via Workflow.Run().
This way, the library will rescue any panic, log the stack trace and show an
error message to the user in Alfred.

	// script_filter.go

	package main

	// Import name is "aw"
	import "github.com/deanishe/awgo"

	// aw.Workflow is the main API
	var wf *aw.Workflow

	func init() {
		// Create a new *Workflow using default configuration
		// (workflow settings are read from the environment variables
		// set by Alfred)
		wf = aw.New()
	}

	func main() {
		// Wrap your entry point with Run() to catch and log panics and
		// show an error in Alfred instead of silently dying
		wf.Run(run)
	}

	func run() {
		// Create a new item
		wf.NewItem("Hello World!")
		// And send the results to Alfred
		wf.SendFeedback()
	}


In the Script box (Language = "/bin/bash"):

	./script_filter


Script Filters

To generate results for Alfred to show in a Script Filter, use the feedback
API of Workflow:

	// Create new items
	NewItem()
	NewFileItem()
	NewWarningItem()

	// Sorting/filtering results
	Filter()

	// Send feedback to Alfred
	SendFeedback()

	// Warning/error calls that drop all other Items on the floor
	// and send feedback immediately
	Warn()
	WarnEmpty()
	Fatal()      // exits program
	Fatalf()     // exits program
	FatalError() // exits program

You can set workflow variables (via feedback) with Workflow.Var, Item.Var
and Modifier.Var.

See Workflow.SendFeedback for more documentation.


Run Script actions

Alfred requires a different JSON format if you wish to set workflow variables.

Use the ArgVars (named for its equivalent element in Alfred) struct to
generate output from Run Script actions.

Be sure to set TextErrors to true to prevent Workflow from generating
Alfred JSON if it catches a panic:

	wf.Configure(aw.TextErrors(true))

See ArgVars for more information.


Configuration

New() creates a *Workflow using the default values and workflow settings
read from environment variables set by Alfred.

You can change defaults by passing one or more Options to New(). If
you do not want to use Alfred's environment variables, or they aren't set
(i.e. you're not running the code in Alfred), use NewFromEnv() with a custom
Env implementation.

A Workflow can be re-configured later using its Configure() method.

See the documentation for Option for more information on configuring a Workflow.


Updates

AwGo can check for and install new versions of your workflow.
Subpackage update provides an implementation of the Updater interface and
sources to load updates from GitHub or Gitea releases, or from the URL of
an Alfred `metadata.json` file.

See subpackage update and _examples/update.


Fuzzy filtering

AwGo can filter Script Filter feedback using a Sublime Text-like fuzzy
matching algorithm.

Workflow.Filter() sorts feedback Items against the provided query, removing
those that do not match.

See _examples/fuzzy for a basic demonstration, and _examples/bookmarks for a
demonstration of implementing fuzzy.Sortable on your own structs and customising
the fuzzy sort settings.

Fuzzy matching is done by package https://godoc.org/go.deanishe.net/fuzzy


Logging

AwGo automatically configures the default log package to write to STDERR
(Alfred's debugger) and a log file in the workflow's cache directory.

The log file is necessary because background processes aren't connected
to Alfred, so their output is only visible in the log. It is rotated when
it exceeds 1 MiB in size. One previous log is kept.

AwGo detects when Alfred's debugger is open (Workflow.Debug() returns true)
and in this case prepends filename:linenumber: to log messages.


Workflow settings

The Config struct (which is included in Workflow as Workflow.Config) provides an
interface to the workflow's settings from the Workflow Environment Variables panel
(see https://www.alfredapp.com/help/workflows/advanced/variables/#environment).

Alfred exports these settings as environment variables, and you can read them
ad-hoc with the Config.Get*() methods, and save values back to Alfred/info.plist with
Config.Set().

Using Config.To() and Config.From(), you can "bind" your own structs to the
settings in Alfred:

	// Options will be populated from workflow/environment variables
	type Options struct {
		Server   string `env:"HOSTNAME"`
		Port     int    // use default: PORT
		User     string `env:"USERNAME"`
		Password string `env:"-"` // ignore
	}

	cfg := NewConfig()
	opts := &Options{}

	// Populate Options from the corresponding environment variables.
	if err := cfg.To(opts); err != nil {
		// handle error
	}

	// Save Options back to Alfred/info.plist.
	if err := cfg.From(opts); err != nil {
		// handle error
	}

See the documentation for Config.To and Config.From for more information,
and _examples/settings for a demo workflow based on the API.


Alfred actions

The Alfred struct provides methods for the rest of Alfred's AppleScript
API. Amongst other things, you can use it to tell Alfred to open, to search
for a query, to browse/action files & directories, or to run External Triggers.

See documentation of the Alfred struct for more information.


Storing data

AwGo provides a basic, but useful, API for loading and saving data.
In addition to reading/writing bytes and marshalling/unmarshalling to/from
JSON, the API can auto-refresh expired cache data.

See Cache and Session for the API documentation.

Workflow has three caches tied to different directories:

    Workflow.Data     // Cache pointing to workflow's data directory
    Workflow.Cache    // Cache pointing to workflow's cache directory
    Workflow.Session  // Session pointing to cache directory tied to session ID

These all share (almost) the same API. The difference is in when the data go
away.

Data saved with Session are deleted after the user closes Alfred or starts
using a different workflow. The Cache directory is in a system cache
directory, so may be deleted by the system or "system maintenance" tools.

The Data directory lives with Alfred's application data and would not
normally be deleted.


Scripts and background jobs

Subpackage util provides several functions for running script files and
snippets of AppleScript/JavaScript code. See util for documentation and
examples.

AwGo offers a simple API to start/stop background processes via Workflow's
RunInBackground(), IsRunning() and Kill() methods. This is useful for
running checks for updates and other jobs that hit the network or take a
significant amount of time to complete, allowing you to keep your Script
Filters extremely responsive.

See _examples/update and _examples/workflows for demonstrations of this API.


Links

Docs:     https://godoc.org/github.com/deanishe/awgo

Source:   https://github.com/deanishe/awgo

Issues:   https://github.com/deanishe/awgo/issues

Licence:  https://github.com/deanishe/awgo/blob/master/LICENCE
*/
package aw