Type: Package
Title: Wrapper for the 'Hypothes.is' Web Annotation Service
Version: 0.1.1
Description: Interact with the application programming interface for the web annotation service 'Hypothes.is' (See http://hypothes.is for more information.) Allows users to download data about public annotations, and create, retrieve, update, and delete their own annotations.
Imports: dplyr, httr, jsonlite
License: MIT + file LICENSE
LazyData: TRUE
RoxygenNote: 5.0.1
Suggests: testthat
URL: https://github.com/mdlincoln/hypothesisr
BugReports: https://github.com/mdlincoln/hypothesisr/issues
NeedsCompilation: no
Packaged: 2016-07-01 14:07:42 UTC; admin
Author: Matthew Lincoln [aut, cre]
Maintainer: Matthew Lincoln <matthew.d.lincoln@gmail.com>
Repository: CRAN
Date/Publication: 2016-07-01 16:33:31

hypothesisr: Wrapper for the Hypothes.is API

Description

Interact with the API for the web annotation service hypothes.is. Allows users to add, search for, and retrieve annotation data.

Create annotations

Description

Create annotations

Usage

hs_create(token, uri, user, permissions = list(read = "group:__world__",
  update = user, delete = user, admin = user), document = NULL,
  target = NULL, tags = NULL, text, custom = NULL)

Arguments

token

Character. Your account token, which you can generate at https://hypothes.is/register

uri

Character. The URI to be annotated.

user

Character. Your user account, normally in the format acct:username@hypothes.is

permissions

A named list with read, update, delete, and admin permissions. Defaults to setting global read permissions (group:__world__) and setting the user string for update, delete, and admin permissions.

document

A list describing the document. CURRENTLY IGNORED.

target

A list describing the highlight position of the annotation. CURRENTLY IGNORED

tags

Character. (optional) Tags to apply to the annotation.

text

Character. Text to put in the body of the annotation. This will be coerced into a character vector of length 1 using paste.

custom

Add arbitrary fields to the JSON object submitted to hypothes.is by means of a named list.

Value

Upon successful creation, returns a 22-character annotation ID. This ID may be retrieved using hs_read.

Source

https://h.readthedocs.io/en/latest/api/#create

Examples

## Not run: 
hs_create(token = user_token,
uri = "https://github.com/mdlincoln/hypothesisr",
user = "acct:mdlincoln@hypothes.is", tags = c("testing", "R"),
text = "R made me!")

## End(Not run)

Delete an annotation

Description

Delete an annotation

Usage

hs_delete(token, id)

Arguments

token

Character. Your account token, which you can generate at https://hypothes.is/register

id

Character. A hypothes.is annotation id.

Value

TRUE on successful deletion.

Source

https://h.readthedocs.io/en/latest/api/#delete

Retrieve a single annotation by ID

Description

Retrieve a single annotation by ID

Usage

hs_read(id)

Arguments

id

Character. A hypothes.is annotation id.

Value

A dataframe with the contents of that annotation.

Source

https://h.readthedocs.io/en/latest/api/#read

Examples

hs_read("WFMnSC3FEeaNvLeGkQeJbg")

Create a reply to a comment

Description

This is a utility wrapper around hs_create that takes an original comment ID and creates a reply to it by adding the custom references field when constructing the annotation. Normal fields like

Usage

hs_reply(token, user, id, text, ...)

Arguments

token

Character. Your account token, which you can generate at https://hypothes.is/register

user

Character. Your user account, normally in the format acct:username@hypothes.is

id

Character. The annotation ID to reply to.

text

Character. Text to put in the body of the annotation. This will be coerced into a character vector of length 1 using paste.

...

Other arguments to pass to hs_create.

Description

Search hypothes.is annotations.

Usage

hs_search(limit = NULL, offset = NULL, sort = "updated", order = "asc",
  uri = NULL, user = NULL, text = NULL, any = NULL, custom = list())

Arguments

limit

Integer. The maximum number of annotations to return. (Default: 20)

offset

Integer The minimum number of initial annotations to skip. This is used for pagination. For example if there are 65 annotations matching our search query and we're retrieving up to 30 annotations at a time, then to retrieve the last 5, set offset = 5. (Default = 0)

sort

Character. Specify which field the annotations should be sorted by: consumer, created, id, text, updated, uri, user.

order

Character. Specify which order annotations should be sorted by: asc or desc.

uri

Character. Search for annotations of a particular URI, for example www.example.com. URI searches will also find annotations of equivalent URIs. For example if the HTML document at http://www.example.com/document.html? includes a <link rel="canonical" href="http://www.example.com/canonical_document.html"> then annotations of http://www.example.com/canonical_document.html will also be included in the search results. Other forms of document equivalence that are supported include rel="alternate" links, DOIs, PDF file IDs, and more.

user

Character. Search for annotations by a particular user. For example, tim will find all annotations by users named tim at any provider, while tim@hypothes.is will only find annotations by tim on hypothes.is

text

Character. Search for annotations whose body text contains some text, for example: foobar.

any

Character. Search for annotations whose quote, tags, text, uri.parts or user fields match some query text.

custom

A named list of any field in the results returned by hypothes.is as a name, and the search text as values.

Value

A dataframe with annotation data.

Note

If any vectors are passed to these arguments, only the first values will be used.

Source

https://h.readthedocs.io/en/latest/api/#search

Examples

# Search for no more than 5 annotations containing the text "ulysses"
hs_search(text = "ulysses", limit = 5)
# Search with a custom field for tags
hs_search(custom = list(tags = "todo"))
# use the 'uri.parts' field to find annotations on a given domain (exclude
# the TLD, as this will result in all annotations on sites with, e.g., .org,
# as well.)
hs_search(custom = list(uri.parts = "programminghistorian"))

Retreive all annotation search results as a data frame

Description

Takes the same arguments as hs_search and pages through all available results, formatting the output as a data.frame.

Usage

hs_search_all(sort = "updated", order = "asc", uri = NULL, user = NULL,
  text = NULL, any = NULL, custom = list(), pagesize = 200,
  progress = interactive())

Arguments

sort

Character. Specify which field the annotations should be sorted by: consumer, created, id, text, updated, uri, user.

order

Character. Specify which order annotations should be sorted by: asc or desc.

uri

Character. Search for annotations of a particular URI, for example www.example.com. URI searches will also find annotations of equivalent URIs. For example if the HTML document at http://www.example.com/document.html? includes a <link rel="canonical" href="http://www.example.com/canonical_document.html"> then annotations of http://www.example.com/canonical_document.html will also be included in the search results. Other forms of document equivalence that are supported include rel="alternate" links, DOIs, PDF file IDs, and more.

user

Character. Search for annotations by a particular user. For example, tim will find all annotations by users named tim at any provider, while tim@hypothes.is will only find annotations by tim on hypothes.is

text

Character. Search for annotations whose body text contains some text, for example: foobar.

any

Character. Search for annotations whose quote, tags, text, uri.parts or user fields match some query text.

custom

A named list of any field in the results returned by hypothes.is as a name, and the search text as values.

pagesize

Integer. How many annotations to retrieve per query. Between 1 and 200. (Default: 200)

progress

Boolean. Should a progress bar be displayed during download?

Value

A dataframe with annotation data.

Examples

## Not run: 
hs_search_all(text = "arxiv")

## End(Not run)

Update annotations

Description

Update annotations

Usage

hs_update(token, id, uri = NULL, user = NULL, permissions = NULL,
  document = NULL, target = NULL, tags = NULL, text = NULL,
  custom = NULL)

Arguments

token

Character. Your account token, which you can generate at https://hypothes.is/register.

id

Character. A hypothes.is annotation id.

uri

Character. The URI to be annotated.

user

Character. Your user account, normally in the format acct:username@hypothes.is

permissions

A named list with read, update, delete, and admin permissions. Defaults to setting global read permissions (group:__world__) and setting the user string for update, delete, and admin permissions.

document

A list describing the document. CURRENTLY IGNORED.

target

A list describing the highlight position of the annotation. CURRENTLY IGNORED

tags

Character. (optional) Tags to apply to the annotation.

text

Character. Text to put in the body of the annotation. This will be coerced into a character vector of length 1 using paste.

custom

Add arbitrary fields to the JSON object submitted to hypothes.is by means of a named list.

Value

TRUE on successful update.

Source

https://h.readthedocs.io/en/latest/api/#update

Examples

## Not run: 
hs_update(user_token, "lDf9rC3EEea6ck-G5kLdXA", text = "Now even more annotate-y!")

## End(Not run)

Functions for opening an annotation in the system browser

Description

Functions for opening an annotation in the system browser

Usage

open_context(id)

open_annotation(id)

open_uri(id)

Arguments

id

Annotation ID.

Functions