Scripting Papers 3 for Mac with AppleScript – A Getting Started Guide

About
AppleScript

AppleScript is an
object-oriented scripting language with an English-like language
syntax. It can be used on OS X to automate repetitive tasks,
combine features from multiple scriptable applications, and to
create complex workflows.

AppleScript language
essentials

Getting data

In order to get data from Papers, you need to specify Papers as
the target of your AppleScript commands with a so called "tell
statement". I.e., all your Papers-related commands are wrapped
within a tell application "Papers" block:

tell application "Papers"
get publication items
end tell

A tell statement specifies a default target for all commands
contained within it. If you have only one command, you can also
include the tell statement on the same line:

tell application "Papers" to get publication items

In the above examples, we use the get command to
fetch a list of all publications in the current library. The
get command has itself a target (in this case,
publication items) which is the object that responds
to the command. The command's target appears immediately next to
the command and is also called the "direct parameter" of the
command.

Lists

In AppleScript, a list is an ordered collection of values of any
class. Lists are indicated with braces, and values in a list are
separated by commas. As an example, the following command assigns a
list with 4 items – two integer numbers, some text and a
decimal ("real") number – to a variable named "myList":

set myList to {1, 7, "Beethoven", 4.5}

The elements (see below) of lists are
referred to as "items". You can refer to any list item by its item
number. For example, for the above list, the following commands
would all return the integer 7:

get item 2 of myList
get 2nd item of myList
get second item of myList

Here's some other examples how list items can be accessed:

get last item of myList
get items 2 thru 3 of myList

You can also use front or back to
refer to the first or last element, respectively. This is often
used when referring to application windows:

Properties

A property of an object is a characteristic that has a single
value and a label, such as the title property of a
publication:

tell application "Papers"
get title of first item of publication items
end tell

Property values can be read/write or read only. The picture
below lists all properties (and example values) of the Papers
library window (an icon next to each property indicates a read-only
property):

You can get all properties of an object at once:

tell application "Papers"
get properties of first item of publication items
end tell

The result is a "record". Here's part of the record resulting
from the above command:

Records

A record is an unordered collection of labeled properties
(key-value pairs). A record appears in a script as a series of
property definitions contained within braces and separated by
commas. Each property definition consists of a unique label, a
colon, and a value for the property. For example, the following is
a record with three properties:

{title:"My great new paper", publication year:"2012", my rating:5}

Elements

An element is an object contained within another object. An
object can contain many elements or none, and the number of
elements that it contains may change over time. The publications in
your Papers library usually have related objects such as the
publication's authors, editors, keywords or supplemental files.
These are defined as elements. Here's an example that shows the
elements defined for a publication:

Similar to properties, you can access these elements using the
of keyword:

tell application "Papers"
get author items of first item of publication items
end tell

Filtering

A filter specifies all objects in a container (such as a
collection of objects/elements) that match a condition, or test,
specified by a Boolean expression. In effect, a filter reduces the
number of objects in a container.

As an example, instead of specifying every publication in your
Papers library, the following returns just those publications that
have the word "review" in their title:

tell application "Papers"
get every publication item whose title contains "review"
end tell

A term that uses the filter form is also known as a
whose clause. You can use the words where
or that as synonyms for whose. Note that
the filter form works with application objects only. I.e., it
cannot be used to filter the AppleScript objects list,
record, or text.

The return value of a filter reference form is a list of the
objects that pass the test. If no objects pass the test, the list
is an empty list: {}. You can also combine multiple
tests within a single whose clause:

A filter reference form could be rewritten in form of a
repeat statement. For example, this is equivalent to
the above:

tell application "Papers"
set pubList to every publication item
set myList to {}
repeat with i from 1 to count of pubList
set aPub to item i of pubList
if title of aPub contains "review" and author names of aPub contains "Thomas" then
copy aPub to end of myList
end if
end repeat
get myList
end tell

While a whose clause is often the fastest way to
obtain the desired information, more complex filtering may only be
possible with a repeat statement.

Scripting
Papers

Papers 3 features extensive AppleScript support that allows to
easily fetch data from a Papers library and to execute commands
(such as import, export or matching of publications). The scripting
support in Papers also enables you to create new data and to set
its most important properties. You can also set the current
selection or change interface-related properties such as the
current view mode.

Object inheritance

The Papers scripting interface exposes object classes for the
most important elements of your Papers library in a hierarchical
data model:

All publication-related object classes descend from an abstract
base class (library item) which contains properties
that are shared among all subclasses: creation/modification date,
id and resource type. I.e., if you get all properties of a concrete
object, e.g.:

tell application "Papers" to get properties of first item of keyword items

the superclass's properties will be returned as well:

AppleScript dictionary

A dictionary is the part of a scriptable application that
specifies the scripting terms it understands. The dictionary
documents all object classes with its properties and elements, and
may contain useful hints or sample code. You can choose "File >
Open Dictionary" in Script Editor to display the dictionary of a
scriptable application such as Papers:

Container hierarchy

A container is an object that contains one or more objects or
properties. The application target (identified by the tell
application "Papers" statement) constitutes the top-level
container. It contains elements for all main object classes:

This allows you to easily get all objects of a certain class.
For instance, this would return all primary (non-supplemental) PDF
files that are available in your Papers library:

tell application "Papers"
get primary file items
end tell

This is the same as above:

tell application "Papers" to get every primary file item

Using the of keyword you can walk along the
container hierarchy and follow the defined object relationships.
For instance, this would return a list of all publications that
have a primary PDF:

tell application "Papers"
get publication item of every primary file item
end tell

Similarly, for each publication with a primary PDF, this would
return a list of all authors of that publication:

tell application "Papers"
get author items of publication item of every primary file item
end tell

The result of the above command is a list of lists where the
root items represent publication items and the sub-items consist of
person items of each publication:

Working with
displayed & selected publications

The library window object has properties to get the
list of displayed publications, and to get or set the list of
selected publications. Here's how to get all displayed
publications:

Please note that, currently, not all available properties are
writable. However, you can also create a new publication just from
a DOI, and Papers will fill in all metadata and download the
fulltext PDF (if it's publicly available):

tell application "Papers"
set newPub to make new publication item with properties {doi:"10.1371/journal.pone.0099776"}
delay 0.5
set selected publications of front library window to (newPub as list)
end tell

Note that, in the last example, the new entry must currently be
selected in order to get the PDF downloaded automatically. We delay
selecting the entry by 0.5 seconds so that Papers has enough time
to create the new publication and display it in the interface. For
an alternative way to create a publication based on a DOI, see
Importing publications
below.

As yet another alternative, you could also create a new
publication with partial metadata (e.g., just the title) and use
the match command to automatically complete missing
metadata (see Matching
publications below).

Updating object properties

You can set new values for any writable object property. For
instance, this would update the title of the first publication
that's currently selected in your Papers library:

tell application "Papers"
set aPub to first item of (selected publications of front library window as list)
set title of aPub to "My great new paper"
end tell

You can also edit multiple objects at once. In most cases,
you'll need to specify a whose clause to only update
objects that match a certain condition. For instance, this command
batch-updates the publication year of all publications that have
the keyword "test" assigned:

tell application "Papers"
set publication year of every publication item whose keyword names contains "test" to 2005
end tell

If you want to batch-update items from the list of selected (or
displayed) publications, you'll currently need to use a
repeat statement instead:

tell application "Papers"
set pubList to selected publications of front library window
repeat with aPub in pubList
set publication year of aPub to 2014
end repeat
end tell

Please be aware that the update of objects is performed
instantly and that this action cannot be undone.

Deleting
objects

As usual, you can also use a whose clause to
specify the list of publications that a command shall act on. For
instance, in the below example, the checks for title
and keyword names ensure that only publications with
title "My great new paper" and with no keywords assigned get
deleted:

tell application "Papers"
delete (every publication item whose title is "My great new paper" and keyword names is "")
end tell

Please be aware that the deletion of objects is performed
instantly and that this action cannot be undone.

Use cases

Importing publications

Use the standard open command to import a
bibliographic metadata file (such as a BibTeX file) or a PDF file
from disk. By default, you need to specify the file's path as an
HFS path which separates path components with a colon:

If replacing metadata is not specified or set to
false (or prefixed with the keyword
without), the matching process will only add missing
information and not replace existing publication metadata. If you
instead set replacing metadata to true
(or prefix it with the keyword with), this will
replace all existing metadata for the currently selected
publications:

Note that this action cannot be undone, and that with
replacing metadata will cause title formatting or additional
information that has been entered for the targeted publication
items to get overridden.

As mentioned above, you can
use the match command to complete metadata for newly
created publications. In the below example, we create a new
publication with just a title, and then let Papers fetch missing
metadata plus the PDF via matching:

tell application "Papers"
set newPub to make new publication item with properties {title:"The Estrogen Hypothesis of Obesity"}
delay 0.5
set selected publications of front library window to (newPub as list)
set matchedPubs to match (newPub as list) without replacing metadata
end tell

Exporting publications

This will export all currently selected publications as BibTeX
to a file (named "Bibliography.bib") on your desktop:

tell application "Papers"
set outFile to ((path to desktop from user domain) as string) & "Bibliography.bib"
export (selected publications of front library window as list) to outFile
end tell

By default, publications will be exported in BibTeX format.
However, you can specify the export format explicitly (e.g., RIS,
EndNote XML or Papers Archive). For example, this will create a RIS
file on your desktop containing all publications that have the
keyword "my papers" assigned:

As yet another example, the following will export all primary
(non-supplemental) PDF files in your library to a folder (named
"PDF Files") on your desktop:

tell application "Papers"
set outFolder to ((path to desktop from user domain) as string) & "PDF Files"
export ((publication item of every primary file item) as list) as PDF Files to outFolder
end tell

Resources

We have created a
public discussion forum for feedback, questions and sample
scripts for the AppleScript support in Papers.

A good compilation of AppleScript tips by Nathan Grigg that
explain, for instance, how to specify files in AppleScript, how to
run an AppleScript from the command line, or how to pass variables
by reference.

Tools

Script Debugger is a
powerful third-party AppleScript debugger. Besides full debugging
capabilities, Script Debugger features advanced dictionary viewers.
It also offers unique value explorers that allow you to dynamically
inspect the objects and properties offered by a scriptable
application. Examples of its dictionary viewers and value explorers
can be seen in some of the screenshots above.