% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cff_write.R
\encoding{UTF-8}
\name{cff_write}
\alias{cff_write}
\title{Write a \code{CITATION.cff} file}
\usage{
cff_write(
  x,
  outfile = "CITATION.cff",
  keys = list(),
  cff_version = "1.2.0",
  gh_keywords = TRUE,
  r_citation = FALSE,
  dependencies = TRUE,
  validate = TRUE,
  verbose = TRUE,
  authors_roles = c("aut", "cre"),
  encoding = "UTF-8"
)
}
\arguments{
\item{x}{The source used to generate
the \code{\link{cff}} object. It can be:
\itemize{
\item A missing value, which retrieves the \code{DESCRIPTION} file from your
in-development \strong{R} package.
\item An existing \code{\link{cff}} object.
\item The name of an installed package (\code{"jsonlite"}).
\item Path to a \code{DESCRIPTION} file (\code{"./DESCRIPTION"}).
}}

\item{outfile}{The name and path of the \code{CITATION.cff} to be created.}

\item{keys}{List of additional keys to add to the \code{\link{cff}} object. See
\code{\link[=cff_modify]{cff_modify()}}.}

\item{cff_version}{The Citation File Format schema version that the
\code{CITATION.cff} file adheres to for providing the citation metadata.}

\item{gh_keywords}{Logical \code{TRUE/FALSE}. If the package is hosted on
GitHub, would you like to add the repo topics as keywords?}

\item{r_citation}{Logical \code{TRUE/FALSE}. When \code{TRUE}, the \strong{R} package
citation (for example, \code{inst/CITATION}) is created or updated.
\strong{No backup copy is created}. For more control, use
\code{\link[=cff_write_citation]{cff_write_citation()}}.}

\item{dependencies}{Logical \code{TRUE/FALSE}. Should the dependencies of your
package be added to the \code{references} CFF key?}

\item{validate}{Logical \code{TRUE/FALSE}. Should the new file be validated
using \code{cff_validate()}?}

\item{verbose}{Logical \code{TRUE/FALSE}. When \code{TRUE}, the function displays
informative messages.}

\item{authors_roles}{Roles to be considered as authors of the package when
generating the \code{CITATION.cff} file. See \strong{Details}.}

\item{encoding}{The name of the encoding to be assumed. Default is \code{"UTF-8"},
but it can be any other value as accepted by \code{\link[=iconv]{iconv()}}, such as
\code{"ASCII//TRANSLIT"}.}
}
\value{
A \code{CITATION.cff} file and an (invisible) \code{cff} object.
}
\description{
\strong{This is the core function of the package and likely to be the only one
you would need when developing a package}.

This function writes out a \code{CITATION.cff} file for a given package. This
function is basically a wrapper around \code{\link[=cff_create]{cff_create()}} to both create the
\code{\link{cff}} object and write it out to a YAML-formatted file in
one command.
}
\details{
For details of \code{authors_roles} see \code{\link[=cff_create]{cff_create()}}.

When creating and writing a \code{CITATION.cff} for the first time, the function
adds the pattern \code{"^CITATION\\.cff$"} to your \code{.Rbuildignore} file.
}
\examples{
\donttest{
tmpfile <- tempfile(fileext = ".cff")
cff_obj <- cff_write("jsonlite", outfile = tmpfile)

cff_obj

# Force clean-up
file.remove(tmpfile)
}
}
\seealso{
\href{https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md}{Guide to Citation File Format schema version 1.2.0}.
This function unifies the workflow \code{\link[=cff_create]{cff_create()}} + \code{\link[=cff_validate]{cff_validate()}} +
write a file.

Other functions for creating external files:
\code{\link[=cff_write_bib]{cff_write_bib()}}
}
\concept{writing}
