github.com/quantumghost/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