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  -->