Version: 0.3.6
Date: 2020-12-08
Title: R Client for the COLOURlovers API
Imports: XML, jsonlite, httr, png, graphics, utils
Suggests: httptest, testthat, vdiffr
Description: Provides access to the COLOURlovers https://www.colourlovers.com/ API, which offers color inspiration and color palettes.
License: GPL-2
URL: https://github.com/andrewheiss/colourlovers
BugReports: https://github.com/andrewheiss/colourlovers/issues
Encoding: UTF-8
RoxygenNote: 7.1.1
NeedsCompilation: no
Packaged: 2020-12-09 19:13:44 UTC; andrew
Author: Andrew Heiss ORCID iD [aut, cre], Thomas J. Leeper ORCID iD [aut]
Maintainer: Andrew Heiss <andrew@andrewheiss.com>
Repository: CRAN
Date/Publication: 2020-12-09 19:20:02 UTC

R client for the COLOURlovers API

Description

Provides access to the COLOURlovers API for accessing colors and color palettes for use in R graphics.

Author(s)

Thomas J. Leeper

Retrieve color or colors

Description

Retrieve a color or set of colors from the COLOURlovers API.

Usage

clcolors(set = NULL, ..., fmt = "xml")

clcolor(hex, fmt = "xml")

Arguments

set

Optionally, a subset of COLOURlovers colors. Allowed values are “new”, “top”, and “random”.

...

A named list of parameters passed to the API request. Allowed parameters are lover, hueRange, briRange, keywords, keywordExact, orderCol, sortBy, numResults, and resultOffset. Specifying orderCol overrules any argument to set. See details.

fmt

A format for the API response, one of “xml” (the default) or “json”. This has essentially no effect on function behavior. @return A list of class “clcolor”. This should be the same regardless of the value of fmt.

hex

The six-character hexidemical representation of a single color.

Details

Retrieve details about a color our set of colors.

Specifying named arguments to ... allows the user to request a specific response, as follows:

Author(s)

Thomas J. Leeper

References

http://www.colourlovers.com/api/#colors

Examples

## Not run: 
# Get a random color
clcolors('random')

# Get a single color
clcolor('6B4106')

# Plot a single color
clcolor(rgb(0,0,1), fmt = 'json')

## End(Not run)

Retrieve a user (lover)

Description

Retrieve a lover (user) or set of lovers from the COLOURlovers API.

Usage

cllovers(set = NULL, ..., fmt = "xml")

cllover(user, comments = FALSE, fmt = "xml")

Arguments

set

Optionally, a subset of COLOURlovers palettes. Allowed values are “new” and “top”.

...

A named list of parameters passed to the API request. Allowed parameters are orderCol, sortBy, numResults, and resultOffset. Specifying orderCol overrules any argument to set. See details.

fmt

A format for the API response, one of “xml” (the default) or “json”. This has essentially no effect on function behavior.

user

The COLOURlovers username for a specific user.

comments

A boolean indicating whether to include the last ten comments for the user. Default is FALSE.

Details

Retrieve details about a COLOURlovers user or users.

Specifying named arguments to ... allows the user to request a specific response, as follows:

Value

A list of class “cllover”, including details about one or more users. This should be the same regardless of the value of fmt.

Author(s)

Thomas J. Leeper

References

http://www.colourlovers.com/api/#lovers

Examples

## Not run: 
# Retrieve top users
cllovers(set = 'top', fmt = 'json')

# Retrieve a single user
cllover('COLOURlovers', fmt = 'json')

## End(Not run)

Retrieve color palette or palettes

Description

Retrieve a color palette or set of palletes from the COLOURlovers API.

Usage

clpalettes(set = NULL, ..., fmt = "xml")

clpalette(id, widths = FALSE, fmt = "xml")

Arguments

set

Optionally, a subset of COLOURlovers palettes. Allowed values are “new”, “top”, and “random”.

...

A named list of parameters passed to the API request. Allowed parameters are lover, hueOption, hex, hex_logic, keywords, keywordExact, orderCol, sortBy, numResults, and resultOffset. Specifying orderCol overrules any argument to set. See details.

fmt

A format for the API response, one of “xml” (the default) or “json”. This has essentially no effect on function behavior.

id

The COLOURlovers id (an integer) for a specific palette.

widths

A boolean indicating whether to include the color widths for the palette. Default is FALSE.

Details

Retrieve details about a palette or set of palettes.

Specifying named arguments to ... allows the user to request a specific response, as follows:

Value

A list of class “clpalette”. This should be the same regardless of the value of fmt.

Author(s)

Thomas J. Leeper

References

http://www.colourlovers.com/api/#palettes

Examples

## Not run: 
# Get a random palette
clpalettes('random')

# Download top palettes
clpalettes('top', fmt = 'json')

# Plot a single palette
pid <- '113451'
p <- clpalette(pid, fmt = 'json')
plot(p)

## End(Not run)

Retrieve pattern or patterns

Description

Retrieve a pattern or set of patterns from the COLOURlovers API.

Usage

clpatterns(set = NULL, ..., fmt = "xml")

clpattern(id, fmt = "xml")

Arguments

set

Optionally, a subset of COLOURlovers patterns. Allowed values are “new”, “top”, and “random”.

...

A named list of parameters passed to the API request. Allowed parameters are lover, hueOption, hex, hex_logic, keywords, keywordExact, orderCol, sortBy, numResults, and resultOffset. Specifying orderCol overrules any argument to set. See details.

fmt

A format for the API response, one of “xml” (the default) or “json”. This has essentially no effect on function behavior.

id

The COLOURlovers id (an integer) for a specific pattern.

Details

Retrieve details about a pattern or set of patterns.

Specifying named arguments to ... allows the user to request a specific response, as follows:

Value

A list of class “clpattern”. This should be the same regardless of the value of fmt.

Author(s)

Thomas J. Leeper

References

http://www.colourlovers.com/api/#patterns

Examples

## Not run: 
# Get a random pattern
clpatterns('random')

# Plot a single pattern
p <- clpattern('1451', fmt = 'json')
plot(p)

## End(Not run)

Plot a COLOURlovers object

Description

Plot a color, palette, or pattern color pie or PNG image in a plotting device

Usage

clpng(x, ask = TRUE, ...)

clpie(x, ask = TRUE, ...)

## S3 method for class 'clcolor'
plot(x, type = "png", ...)

Arguments

x

A colourlovers color, palette, or pattern object.

ask

A boolean indicating if plots should be presented interactively or all at once (default is FALSE).

...

Ignored.

type

One of “png” (the default) or “pie”.

Details

Plot a colourlovers PNG image in a new plotting window.

Value

The x object is invisibly returned.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
# Plot a color clpng
co <- clcolor(rgb(0, 0, 1))
plot(co)

# Plot a pattern clpng
p <- clpattern('1451')
plot(p)
clpng(p)

# Plot colors from a palette
p <- clpalette('113451')
plot(p, type = 'pie')
clpie(p)

# Plot multiple palettes (interactively)
p <- clpalettes('top')
plot(p) #  PNG images
plot(p, type = 'pie')  # pie chart swatches

## End(Not run)

Execute an API Query

Description

Primarily an internal function for executing API calls.

Usage

clquery(type, set = NULL, query = NULL, fmt = "xml", ...)

Arguments

type

An API type. One of “colors”, “palettes”, “patterns”, “lovers”, or “stats”.

set

A further subtype of the API type.

query

An optional character string specifying additional query parameters.

fmt

A format for the API response, one of “xml” (the default) or “json”.

...

Ignored.

Details

Primarily for internal use.

Value

A list reflecting the API response. This should be the same regardless of the vale of fmt.

Author(s)

Thomas J. Leeper

Retrieve basic statistics from COLOURlovers.

Description

Retrieve basic statistics from the COLOURlovers API.

Usage

clstats(type, fmt = "xml")

Arguments

type

An API type. One of “colors”, “palettes”, “patterns”, or “lovers”.

fmt

A format for the API response, one of “xml” (the default) or “json”. This has essentially no effect on function behavior.

Details

Retrieve total numbers of colors, palettes, patterns, or lovers.

Value

A numeric value of class “clstats”. This should be the same regardless of the value of fmt.

Author(s)

Thomas J. Leeper

References

http://www.colourlovers.com/api/#stats

Examples

## Not run:  
clstats('colors')
clstats('palettes')
clstats('patterns')
clstats('lovers')

## End(Not run)

Extract colors from an object

Description

Extract a list of colors from a COLOURlovers object

Usage

swatch(x, ...)

Arguments

x

A colourlovers color, palette, or pattern object.

...

Ignored.

Details

Extract color(s) from a colourlovers object.

Value

A list of character vectors containing hexidecimal representations of colors.

Author(s)

Thomas J. Leeper

Examples

## Not run: 
# Get top colors
swatch(clcolors('top'))

# Get colors from a specific palette
swatch(clpalette('113451'))

# Get colors from specific pattern
swatch(clpattern('1451'))

## End(Not run)