---
title: "Styling with tergo"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Styling with tergo}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(tergo)
```

# Get Started with `tergo`

`tergo` is a lightning-fast R code formatter powered by Rust, designed for developers who prioritize speed and efficiency. 
Whether you're optimizing CI pipelines or building responsive developer tools, `tergo` reformats R code in milliseconds.

## Installation

### Method 1: From R-Universe (Recommended for Most Users)
No Rust tooling required. Binaries are pre-built:
```r
install.packages('tergo', repos = c(
  'https://kpagacz.r-universe.dev',
  'https://cloud.r-project.org'
))
```

### Method 2: From GitHub Sources (For Advanced Users)
Requires [Rust toolchain](https://www.rust-lang.org/tools/install):
```r
if (!require(remotes)) install.packages("remotes")
remotes::install_github("kpagacz/tergo@latest", subdir = "antidotum/tergo")
```

## Basic Usage
Style your entire R package:
```r
tergo::style()  # Run in package root directory
```

Style specific files/directories:
```r
tergo::style("path/to/your-script.R")
tergo::style(c("dir1/", "dir2/")) 
```

## Configuration Options
Customize formatting via `tergo.toml` in your package root or through function arguments.

### Example `tergo.toml`
```toml
indent = 4
line_length = 80
embracing_op_no_nl = false
function_line_breaks = "double"
```

### Inline Configuration
Override settings programmatically:
```r
tergo::style(config = list(
  indent = 4,
  allow_nl_after_assignment = TRUE
))
```

### Full Configuration Reference
| Option                              | Type   | Default | Description |
|-------------------------------------|--------|---------|-------------|
| `indent`                           | integer | 2      | Spaces per indent level |
| `line_length`                      | integer | 120    | Maximum line length before wrapping |
| `embracing_op_no_nl`               | boolean | TRUE   | Remove line breaks in `{{ }}` ([ref](https://style.tidyverse.org/syntax.html#embracing)) |
| `allow_nl_after_assignment`        | boolean | FALSE  | Permit line breaks after `=`, `<-`, `:=` |
| `space_before_complex_rhs_in_formula` | boolean | TRUE | Add space before complex RHS in formulas ([ref](https://style.tidyverse.org/syntax.html#infix-operators)) |
| `strip_suffix_whitespace_in_function_defs` | boolean | TRUE | Trim trailing whitespace in functions |
| `function_line_breaks`             | string  | "hanging" | `"single"`/`"double"`/`"hanging"` function argument formatting ([ref](https://style.tidyverse.org/functions.html#multi-line-function-definitions)) |
| `insert_newline_in_quote_call`     | boolean | TRUE   | Add newlines in long `quote()` calls |

## Why Choose `tergo`?
- **Blazing Fast**: Formats large codebases 100-1000x faster than alternatives
- **CI-Friendly**: Reduces CI runtime/costs by orders of magnitude
- **Low-Config Efficiency**: Sensible defaults with focused customization
- **Native Performance**: Rust core ensures consistent speed regardless of input size

## Advanced Usage
### Benchmarking
Verify performance claims using included benchmarks:
```r
source(system.file("bench.R", package = "tergo")) 
```

### Project-Specific Configs
Maintain different `.toml` files for multiple projects:
```r
tergo::style(config = "path/to/alternate.toml")
```

---

**Next Steps**:  
• Run `?tergo::style` for detailed function documentation  
• Visit [GitHub repository](https://github.com/kpagacz/tergo) for issue tracking  
• Experiment with different `.toml` configurations to match your team's style guide
```