Title: Lite Wrapper for the 'Zamzar File Conversion' API
Version: 0.1.2
Date: 2020-03-17
Author: Frederik Kok Hansen
Maintainer: Frederik Kok Hansen <frederik_kok@icloud.com>
Description: A minor collection of HTTP wrappers for the 'Zamzar File Conversion' API. The wrappers makes it easy to utilize the API and thus convert between more than 100 different file formats (ranging from audio files, images, movie formats, etc., etc.) through an R session. For specifics regarding the API, please see https://developers.zamzar.com/.
Imports: httr, jsonlite
Suggests: httptest, roxygen2, testthat, knitr, rmarkdown
License: GPL-3
RoxygenNote: 7.0.2
Encoding: UTF-8
Language: en-US
BugReports: https://github.com/fkoh111/zzlite/issues
Depends: R (≥ 3.2)
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2020-03-17 08:28:26 UTC; fkoh111
Repository: CRAN
Date/Publication: 2020-03-18 15:20:02 UTC

Auxiliary function

Description

Wrapper for httr::authenticate

Usage

.zz_authenticate(usr)

Auxiliary function

Description

Function that deals with paging

Usage

.zz_do_paging(content, container, endpoint, usr)

Auxiliary function

Description

Decorate an endpoint with a content path

Usage

.zz_endpoint_content(endpoint, id)

Auxiliary function

Description

Get Zamzar key from .Renviron

Usage

.zz_get_key(usr)

Auxiliary function

Description

Wrapper for parsing of responses

Usage

.zz_parse_response(response)

Auxiliary wrapper for user agent

Description

Auxiliary wrapper for user agent

Usage

.zz_user_agent()

Delete file from Zamzar account

Description

Delete file from Zamzar account provided a file id.

Usage

zz_delete(id = NULL, usr = NULL, verbose = FALSE)

Arguments

id

The target id for a file you wish to delete. Most likely returned from ‘zz get info()‘.

usr

The username/API key you are using. If not set, the function will check if a key exists as a 'ZAMZAR_USR' variable in '.Renviron' and use that.

See: https://developers.zamzar.com/user

verbose

Boolean deciding whether or not verbose status messages should be returned. Defaults to 'FALSE'.

Details

Please note that a Zamzar key passed as argument to 'usr' takes precedence over a Zamzar key extracted from an '.Renviron'.

Value

A status message indicating either success or failure.

Examples

## Not run: 
# An example of zz_delete() with a hardcoded file id

zz_get(id = 12345678)

## End(Not run)

Accepted formats from Zamzar

Description

Get dataframe of all the formats accepted by Zamzar. Alternatively, a dataframe of formats you can convert an origin to.

Usage

zz_format(origin = NULL, usr = NULL)

Arguments

origin

The origin format you want to convert from. If a valid argument is passed to origin, zz_format() returns a dataframe of:

  • targets: The formats your origin can be converted to.

  • costs: The cost for converting between your origin and a given target.

See also: https://developers.zamzar.com/formats

If no argument has been passed to orign, a dataframe containing all the accepted formats by the Zamzar API is returned.

See: https://developers.zamzar.com/formats

usr

The username/API key you are using. If not set, the function will check if a key exists as a ZAMZAR_USR variable in .Renviron and use that.

See: https://developers.zamzar.com/user

Details

Please note that a Zamzar key passed as argument to usr takes precedence over a Zamzar key extracted from an .Renviron.

Value

Either a dataframe of formats that you can convert to, or a dataframe of accepted origin formats.

Examples

## Not run: 
# Returns a single column dataframe of all the accepted formats
# for the origin param.
zz_format(usr = "key")

# Same as above (assuming a valid key in .Renviron).
zz_format()

# Returns an error since the origin argument isn't recognized by the Zamzar API.
zz_format(origin = "invalid_origin")

# Returns a dataframe of targets that origin can be converted to,
# and of the cost of converting to a given target.
zz_format(origin = "emf")

## End(Not run)

Get file from Zamzar account

Description

Get file from Zamzar account provided a file id. Per default ‘zz_get()' assumes that you’re doing development, thus using a development endpoint. Set prod boolean to 'TRUE' to change this behavior.

Usage

zz_get(
  id = NULL,
  usr = NULL,
  name = NULL,
  extension = NULL,
  overwrite = FALSE,
  prod = FALSE
)

Arguments

id

The target id for a previously passed file. Most likely returned from 'zz_get_info()'.

usr

The username/API key you are using. If not set, the function will check if a key exists as a 'ZAMZAR_USR' variable in '.Renviron' and use that.

See: https://developers.zamzar.com/user

name

The name of the file you are fetching from Zamzar. If a name is not assigned to the file, then the id of the file will be used as file name.

extension

The extension of the file you are fetching from Zamzar.

overwrite

Should 'zz_get()' overwrite if a file with the same name already exists in directory. Defaults to 'FALSE'.

prod

Boolean deciding whether to use a production endpoint or a development endpoint. Defaults to FALSE (That is, development endpoint).

Details

On differences between endpoints, see: https://developers.zamzar.com/docs#section-Next_steps and https://developers.zamzar.com/docs#section-Rate_Limits

Please note that a Zamzar key passed as argument to 'usr' takes precedence over a Zamzar key extracted from an '.Renviron'.

Value

A file written to disk.

Examples

## Not run: 
# An example of zz_get() utilized with hardcoded arguments
zz_get(id = 12345678, usr = "key", name = "my_avatar", extension = "png")

# An example of zz_get() used in conjunction with zz_get_info()
# Please note this example assumes a valid key in .Renviron
response <- zz_get_info(latest = TRUE)
zz_get(id = response$id, extension = response$extension, prod = TRUE)

## End(Not run)

Get info from Zamzar

Description

Get info on files submitted to Zamzar by account.

Usage

zz_get_info(usr = NULL, latest = TRUE)

Arguments

usr

The username/API key you are using. If not set, the function will check if a key exists as a ZAMZAR_USR variable in .Renviron and use that.

See: https://developers.zamzar.com/user

latest

Boolean deciding whether or not metadata on all files that have been submitted within a reasonable time frame should be returned.

If switched to FALSE, metadata on all files that have been submitted to the Zamzar API within a reasonable time frame will be returned.

Defaults to TRUE.

The returned dataframe contains the following columns:

  • id: The unique file identifier assigned to a file by Zamzar.

  • extension: The extension representing the format of the file you can download.

  • created_at: The time at which the file was created at the Zamzar servers.

Details

Per default zz_get_info() assumes you want information for the last submitted file. To get information on all the files that have been submitted within a reasonable time frame, set parameter latest to FALSE.

Please note: objects returned from zz_get_info() doesn't differentiate between development or production endpoint. You have to keep track of this yourself.

Please note that a Zamzar key passed as argument to usr takes precedence over a Zamzar key extracted from an .Renviron.

Value

A dataframe.

Examples

## Not run: 
# Provided a valid token in .Renvirion, a dataframe of metadata for the last 
# submitted file will be returned.
zz_get_info()

# Same as above, we're just passing the key in a variable.
zz_get_info(usr = "key")
 
# Provided a valid token, will return metadata for all files
# submitted to the API within a reasonable time frame.
zz_get_info(usr = "key", latest = FALSE)

# Same as above, we're just utilizing .Renviron.
zz_get_info(latest = FALSE)

## End(Not run)

Post file to Zamzar endpoint

Description

Per default ‘zz_post()' assumes that you’re doing development, thus using a development endpoint. Set parameter 'prod' to 'TRUE' to change this behavior.

Usage

zz_post(
  file = NULL,
  extension = NULL,
  usr = NULL,
  prod = FALSE,
  verbose = FALSE
)

Arguments

file

The path to the file you want to convert.

extension

The file type you want to convert to. E.g., 'png'.

usr

The username/API key you are using. If not set, the function will check if a key exists as a 'ZAMZAR_USR' variable in '.Renviron' and use that.

See: https://developers.zamzar.com/user

prod

Boolean deciding whether to use production or development endpoint. Defaults to 'FALSE'.

verbose

Boolean deciding whether or not verbose status messages should be returned. Defaults to 'FALSE'.

Details

On differences between endpoints, see: https://developers.zamzar.com/docs#section-Next_steps and https://developers.zamzar.com/docs#section-Rate_Limits

Please note that a Zamzar key passed as argument to 'usr' takes precedence over a Zamzar key extracted from an '.Renviron'.

Value

A status message indicating either success or failure.

See Also

zz_format for a list of formats you can convert to.

Examples

## Not run: 
# Per default zz_post uses the development endpoint.
zz_post(file = "avatar.emf", extension = "png")

# Setting prod parameter to FALSE is the same as above.
zz_post(file = "avatar.emf", extension = "png", prod = FALSE)

# You need to flip prod to TRUE if you want to use the production endpoint.
zz_post(file = "avatar.emf", extension = "png", prod = TRUE)

# Remember you can always pass a Zamzar key to the usr parameter if you don't
# want to use an .Renviron file.
zz_post(file = "avatar.emf", usr = "key", extension = "png", prod = TRUE)
 

## End(Not run)