README.Rmd

seasl
=====

```{r echo=FALSE}
library("knitr")
hook_output <- knitr::knit_hooks$get("output")
knitr::knit_hooks$set(output = function(x, options) {
   lines <- options$output.lines
   if (is.null(lines)) {
     return(hook_output(x, options))  # pass to default hook
   }
   x <- unlist(strsplit(x, "\n"))
   more <- "..."
   if (length(lines)==1) {        # first n lines
     if (length(x) > lines) {
       # truncate the output, but add ....
       x <- c(head(x, lines), more)
     }
   } else {
     x <- c(if (abs(lines[1])>1) more else NULL,
            x[lines],
            if (length(x)>lines[abs(length(lines))]) more else NULL
           )
   }
   # paste these lines together
   x <- paste(c(x, ""), collapse = "\n")
   hook_output(x, options)
 })

knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE,
  warning = FALSE,
  message = FALSE
)
```

[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
![R build status](https://github.com/ropensci/seasl/workflows/R-CMD-check/badge.svg)
[![rstudio mirror downloads](https://cranlogs.r-pkg.org/badges/seasl?color=C9A115)](https://github.com/metacran/cranlogs.app)
[![cran version](https://www.r-pkg.org/badges/version/seasl)](https://cran.r-project.org/package=seasl)
<!-- [![Build Status](https://travis-ci.org/ropensci/seasl.svg?branch=master)](https://travis-ci.org/ropensci/seasl) -->

`seasl` is an R client for exploring CSL styles.

This package is inspired by the Ruby gem `csl`: https://github.com/inukshuk/csl-ruby

The Citation Style Language 1.0.1 specification: http://docs.citationstyles.org/en/1.0.1/specification.html

Package API:

```{r echo=FALSE, comment=NA, results='asis'}
# cat(paste(" -", paste(sort(getNamespaceExports("seasl")), collapse = "\n - ")))
cat(paste(" -", paste(sprintf("`%s`", getNamespaceExports("seasl")), collapse = "\n - ")))
```

## Install

```{r eval=FALSE}
install.packages("seasl")
```

or

```{r eval=FALSE}
remotes::install_github("ropensci/seasl")
```

```{r}
library("seasl")
```

## Download styles and locales

First, you may want to download style and locale files. `csl_fetch_styles()` and `csl_fetch_locales()`
download the files to your machine. See `?csl_cache` for caching information, including
how to change the cache location.

Styles retrieved from the Github repo at https://github.com/citation-style-language/styles-distribution

```{r eval=FALSE}
csl_fetch_styles()
#>
#> Done! Files put in /Users/sckott/Library/Caches/R/seasl/styles
```

Locales retrieved from the Github repo at https://github.com/citation-style-language/locales

```{r eval=FALSE}
csl_fetch_locales()
#>
#> Done! Files put in /Users/sckott/Library/Caches/R/seasl/locales
```

## File paths to CSL styles and locales

calling `csl_styles` without inputs gives all styles, with separate lists for 
dependent and independent styles

```{r output.lines = 1:10}
csl_styles()
```

calling `csl_styles` with an input gives the path to that style, if found

```{r}
csl_styles("apa")
csl_styles("archeologie-medievale")
```

Same patterns go for locales (note that there are far fewer locales than styles)

```{r}
# just locale names
csl_locales()
```

```{r}
# when locale given, you get the full path
csl_locales("fr-FR")
```

Alternatively, you can try to find a style by using `csl_style_find()`

```{r}
# single match
csl_style_find(x = "American Journal of Epidemiology")
```

```{r output.lines = 1:10}
# many matches
csl_style_find(x = "American Journal")
```

## Load CSL style from a URL

```{r}
jps <- csl_style_load('http://www.zotero.org/styles/american-journal-of-political-science')
```

## Query style information

```{r output.lines = 1:10}
jps$info
```

```{r}
jps$info$title
```

```{r output.lines = 1:10}
jps$macros
```

```{r output.lines = 1:10}
jps$citation
```

```{r output.lines = 1:10}
jps$bibliography
```

## Get raw XML

```{r output.lines=1:10}
csl_style_xml('http://www.zotero.org/styles/american-journal-of-political-science')
```

## Meta

* Please [report any issues or bugs](https://github.com/ropensci/seasl/issues).
* License: MIT
* Citation: execute `citation(package = 'seasl')`
* Please note that this project is released with a [Contributor Code of Conduct][coc]. By participating in this project you agree to abide by its terms.

[![ropensci_footer](https://ropensci.org/public_images/github_footer.png)](https://ropensci.org)

[coc]: https://github.com/ropensci/seasl/blob/master/CODE_OF_CONDUCT.md