开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

PopClip Extensions

This document applies to PopClip 2022.5 (3895). See also: Changelog

NEW: Check the PopClip Forum to keep up-to date about extensions development, to ask questions, and to help others.

Table of Contents

• PopClip Extensions
  • Table of Contents
  • Introduction
    • License
    • Credits
    • Repository Layout & Contributing
    • Extension Signing
    • Debug Output
  • Extension Snippets
    • Extension Snippets Examples
  • Anatomy of a PopClip Extension
    • Types of Actions
    • Filtering
    • The .popclipext package
    • About .popclipextz files
    • The Config file
    • Field names
  • Icons
    • Text-based icons
    • Examples of symbols and text-based icons
  • The Config file structure
    • About the "Localizable String" type
    • Extension properties
    • Action properties
    • Shortcut actions
    • Service actions
    • URL actions
    • Key Press actions
      • Key Combo String Format
    • AppleScript actions
      • The applescript call dictionary
      • AppleScript format
      • Example plain text AppleScript with placeholder strings
      • Example of calling an AppleScript handler with parameters
      • Using JXA Scripts
    • Shell Script actions
      • Example Shell Script Files
      • Shell Script Testing
    • JavaScript actions
      • The JavaScript Engine
      • Error handling and debugging
      • Asynchronous operations and async/await
      • Network access from JavaScript
      • About TypeScript and .ts files
      • JavaScript testing
      • JavaScript language reference
  • Meanings of particular fields
    • The requirements array
      • Note on side effect of requirements field
    • The before and after strings
    • The app dictionary
    • The options array
  • Using Scripts
    • Script Fields
    • Indicating Errors
  • Field name mapping

Introduction

PopClip Extensions add extra actions to PopClip.

This repository contains the documentation for making your own extensions (this readme file) as well as the source files for the extensions published on the official PopClip Extensions page.

License

All extension source files are published under the MIT License (see LICENSE.txt) unless noted otherwise in the readme files of individual extensions.

Credits

All the extensions and documentation were created by Nick Moore, except where stated. Individual extension credits are included in a readme file with the extension.

Repository Layout & Contributing

The important folders:

• source - sources for the published extensions (maintained and supported by me)
• source-contrib - folder for user-submitted and experimental extensions
• extensions - signed and zipped .popclipextz files built from the source and source-contrib folders

Bugfixes and new extension submissions are welcome via pull request. Please note the following:

• New extensions should be submitted as source files in a .popclipext folder inside the source-contrib folder.
• Please do not submit any zipped .popclipextz files.
• By contributing to this repo, you agree that your contribution may be published at PopClip Extensions.
• Submitting an extension does not guarantee publication on the website.
• I may make changes to any extension submitted.

A good place to tell PopClip users about your work is the Show and Tell section in the PopClip forum.

Extension Signing

By default, PopClip will display a warning dialog when you try to install your own extension, because it is not digitally signed.

If you find this gets annoying while you are testing your work, you can turn off the warning. Run the following command at the Terminal, then Quit and restart PopClip:

defaults write com.pilotmoon.popclip LoadUnsignedExtensions -bool YES

Please be aware that PopClip extensions can contain arbitrary executable code. Be careful about the extensions you create, and be wary about loading extensions you get from someone else.

(PopClip will never load unsigned extensions whose identifier has a com.pilotmoon. prefix, which is reserved for 'official' extensions. When basing your own extension off such an extension, you will need to change the identifier.)

Debug Output

To help you when creating extensions, PopClip can be configured to write script output and debug info to be viewed with the Console app. To enable it, run this command in Terminal, then Quit and restart PopClip:

defaults write com.pilotmoon.popclip EnableExtensionDebug -bool YES

Extension Snippets

PopClip 2021.11 supports a new, simplified way to create and share simple extensions called "Extension Snippets".

Here is an example extension snippet:

# popclip extension to search Emojipedia
name: Emojipedia
icon: search filled E
url: https://emojipedia.org/search/?q=***

When you select the above text, PopClip will offer an "Install Extension" action. Clicking it will install the above extension directly, without any need for config files or a .popclipext folder.

The format of a snippet is a simply a regular PopClip extension config in YAML format, with the addition of a comment header beginning with # popclip (with or without a space, not case sensitive).

All features of regular extensions can be used, with the limitation that additional files (such as icon files or scripts) cannot be included. Extension snippets can be a maximum of 1000 characters.

If the extension is of type Shortcut, Service, URL, Key Combo or JavaScript (without network entitlement), the extension snippet will install without the usual "unsigned extension" prompt. AppleScript snippets, and JavaScript snippets with the network entitlement, will still give the unsigned warning.

Full Shell Script extensions can't be expressed as snippets, although you can use an AppleScript to run a simple shell script as a string literal (see example below).

In the absence of an explicit identifier field, the extension is identified by its name. Installing another extension with the same name (or identifier) will overwrite an existing one.

Extension Snippets Examples

A Shortcuts example:

# popclip shortcuts example
name: Run My Shortcut
icon: symbol:moon.stars # Apple SF Symbols
macos version: '12.0' # shortcuts only work on Monterey and above!
shortcut name: My Shortcut Name

An AppleScript example, running a shell script:

# popclip shellscript nested in an applescript 
name: Say
applescript: do shell script "say '{popclip text}'"

A multi-line AppleScript example (the pipe character begins a YAML multi-line string, and the following lines must all be indented with two spaces - not tabs!):

# PopClip LaunchBar example
name: LaunchBar
icon: LB
applescript: | # pipe character begins a multi-line string
  tell application "LaunchBar"
    set selection to "{popclip text}"
  end tell
# the above lines are indented with two spaces. no tabs allowed in YAML!

A JavaScript example, including multiple actions:

# popclip js + multi action example
name: Markdown Formatting
requirements: [text, paste]
actions:
- title: Markdown Bold # note: actions have a `title`, not a `name`
  icon: circle filled B
  javascript: popclip.pasteText('**' + popclip.input.text + '**')
- title: Markdown Italic
  icon: circle filled I
  javascript: popclip.pasteText('*' + popclip.input.text + '*')  

A Key Press example:

# popclip
name: Key Press Example
key combo: command option J

A Service example:

# popclip
name: Make Sticky
service name: Make Sticky

A more complex Key Combo example with a raw key code and using some more fields:

# popclip extension snippet - more complex example
name: Paste and Enter
icon: square monospaced ↵
requirements: [paste]
before: paste
key combo: 0x24 # see https://bit.ly/3wSkQ9I

Anatomy of a PopClip Extension

Types of Actions

There are seven kinds of actions supported by PopClip extensions.

Filtering

Extensions have access to the following filtering mechanisms, to help prevent actions appearing when they are not useful:

• Filter by matching a regular expression.
• Filter by application (either include or exclude).
• Filter by whether cut, copy or paste is available.
• Filter by whether the text contains a URL, email address or file path.
• Filter by the current values of the extensions's options.

The .popclipext package

A PopClip extension consists of a configuration file called either Config.json, Config.yaml or Config.plist, plus (optional) additional files such as icons and scripts, all contained in a directory whose name ends with .popclipext. Such a directory will be treated as a package by Mac OS X. To view the contents of a package, right click it in Finder and choose 'Show Package Contents'.

If you double-click a .popclipext package, PopClip will attempt to load and install it. PopClip stores its installed extensions in ~/Library/Application Support/PopClip/Extensions/.

Here is an example package structure, the 'Say' extension:

    Say.popclipext                  -- Containing folder
       _Signature.plist             -- Signature (official Pilotmoon extensions only)
       Config.plist                 -- Main configuration file
       say.sh                       -- Script file
       speechicon.png               -- Icon file

About .popclipextz files

For distribution, an extension package folder may be zipped and renamed with the extension .popclipextz. You can examine an existing PopClip extension by renaming it with a .zip extension and unzipping it, to reveal a .popclipext package.

The Config file

Every extension must contain a Config file, in either JSON, YAML or plist format.

The Config file must define a single dictionary at its root, which defines the extension. Although the three formats are different, they all can be used to define a dictionary mapping string keys to values. The values can be strings, numbers, booleans, arrays or other dictionaries. (In this documentation the term 'field' is used to refer to a key/value pair in a dictionary.)

The choice of format does not affect the extension functionality in any way, so you can choose whichever format you prefer to work with. (Plist was the original config file format for PopClip extensions for many years, and the JSON and YAML formats were added later.)

Field names

Field names in this document are given in a lowercase form with words separated by spaces, such as required apps. However, PopClip will treat field names in any of the following formats as equivalent:

• Lowercase with spaces: e.g. required apps
• Mixed case with spaces: e.g. Required Apps (this is the original naming format prior to PopClip 2021.11)
• Camel case: e.g. requiredApps
• Pascal case: e.g. RequiredApps
• Snake case: e.g. required_apps
• Kebab case: e.g. required-apps
• Constant case: e.g. REQUIRED_APPS

Rules for transformation are as defined by case-anything, which PopClip uses.

Older versions of PopClip used different names for some fields. Where there is a new name, the old name is also still accepted. A table of old and new is given in Field name mapping.

Icons

Icons may be specified in the icon fields in a few different ways:

• As a filename: <filename>.png or <filename>.svg specifies an image file within the extension package, in either PNG or SVG format. You can create your own with an image editor, or you could use icons from a website like The Noun Project or the macOS app IconJar. Please include any applicable copyright attribution in a README file.

• As an SF Symbol: symbol:<symbol name> specifies an SF Symbols identifier, for example symbol:flame. Symbols are only available on macOS 11.0 and above. Also note that some symbols require higher macOS versions as indicated in the "Availability" panel in Apple's SF Symbols browser app. (If the symbol does not exist on the version of macOS the user is running, it will be as if no icon was specified. Therefore, you should specify an appropriate macos version when using a symbol icon.)

• As a text-based icon: Using a special format, you can instruct PopClip to generate a text-based icon (see below).

PNG and SVG icons should be square and monochrome. The image should be black, on a transparent background. You can use opacity to create shading. PNG icons should be at least 256x256 pixels in size.

Text-based icons

Text-based icons can up to three characters, on their own or within an enclosing shape. They are specified by space-separated keywords followed by the characters to draw.

The following keywords define an enclosing shape (only one of these should be included):

The following keywords modify the way the text is drawn:

Examples of symbols and text-based icons

Text String	Icon Generated
symbol:flame
symbol:hand.raised
symbol:signpost.right
A or text A
circle 1
circle filled 本
square xyz
square filled !
square filled monospaced ()
search E
search filled monospaced £

As a handy tool, the extension IconPreview.popclipextz in this repo will display the icon for a text string you select.

The Config file structure

About the "Localizable String" type

Fields shown as "Localizable String" may be either a string or a dictionary. If you supply a string, that string is always used. If you supply a dictionary mapping language codes (en, fr, zh-hans, etc.) to a string, PopClip will display the string for the user's preferred language if possible, with fallback to the en string.

Extension properties

The following fields are used at the top level of the configuration to define properties of the extension itself. All fields are optional.

If neither actions nor action is defined, PopClip will look at the top level of the plist for an action definition.

Action properties

The following fields define properties common to all actions. All fields are optional.

Additionally, there will be action-specific properties as described in the sections below.

Shortcut actions

In a Shortcut action, PopClip will invoke a Shortcut by name. Shortcuts are only available on macOS 12.0 and above.

A shortcut action is defined by the presence of a shortcut name field, as follows:

The selected text will be sent as input to the service, and any text returned by the shortcut will be available to the after action.

Service actions

In a Service action, PopClip will invoke a named macOS System Service, passing it the selected text.

A service action is defined by the presence of a service name field, as follows:

The name is as shown in the Services menu, for example Add to Deliveries. In some cases, you may need to look into the Info.plist of the application to find the name defined in there under NSServices → NSMenuItem. An example of this is the Make New Sticky Note service which must be called as Make Sticky.

URL actions

In a URL action, PopClip will open a URL in the default browser (or if the current app is a known browser, in the current app). PopClip can open any type of URL, not just web URLs.

A URL action is defined by the presence of a url field, as follows:

You can also put options in the URL, in the same format as for AppleScripts. For example, http://translate.google.com/#auto%7C{popclip option language}%7C{popclip text}.

The string *** will work as a shorthand for {popclip text}.

Key Press actions

In a Key Press action, PopClip will simulate a key press, or sequence of presses, as if it was performed by the user.

A Key Press action is defined by the presence of a key combo or key combos field, as follows:

Key Combo String Format

The string format is a convenient human-readable format that can specify a key and modifiers. It is a space-separated list of one or more modifiers (the order does not matter), followed by the key to press. The key combo string is not case sensitive.

Some examples:

• command b or command B- Hold command, and press 'b' key
• option shift . - Hold option and shift, and press the dot key
• command space - Hold command, and press space bar
• f1 - The F1 key on its own with no modifiers
• option 0x4b - 0x4b is the hex numeric code for 'Keypad Divide'

The key is specified in one of the following ways:

• As a character. For keys which produce a single character. Examples: A, ;, 9.