---
title: "Quick Reference"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Quick Reference}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Quickest Start
```r
put("./src/") |> put_diagram()
```

## Annotation Syntax
```
# put id:"node_id", label:"Description", node_type:"process", input:"in.csv", output:"out.csv"
```

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `label` | **Yes** | - | Human-readable name |
| `id` | No | UUID | Unique identifier |
| `node_type` | No | `process` | `input`, `process`, `output`, `decision`, `start`, `end` |
| `input` | No | - | Comma-separated input files |
| `output` | No | filename | Comma-separated output files |

**Multiline**: End lines with `\` for continuation.

## Comment Prefixes

Find your language:
```
# put  →  R, Python, Shell, Julia, Ruby, YAML, Perl, TOML, Dockerfile, Makefile
-- put →  SQL, Lua, Haskell
// put →  JavaScript, TypeScript, Go, Rust, Java, C, C++, Swift, Kotlin, C#, PHP, Scala, WGSL
% put  →  MATLAB, LaTeX
* put  →  Block comments (/* */ and /** */) in all // languages
```

## Core Functions

| Function | Purpose | Example |
|----------|---------|---------|
| `put()` | Extract annotations | `put("./src/")` |
| `put_diagram()` | Generate Mermaid | `put_diagram(workflow)` |
| `put_auto()` | Auto-detect workflow | `put_auto("./src/")` |
| `put_generate()` | Suggest annotations | `put_generate("./src/")` |
| `put_merge()` | Merge manual + auto | `put_merge("./src/")` |

## Key Parameters

**`put()`** and scan functions:
```r
put(path, pattern, recursive = TRUE, include_line_numbers = FALSE,
    validate = TRUE, exclude = NULL, log_level = NULL)
```

**`put_diagram()`**:
```r
put_diagram(workflow, output = "console", file = NULL, direction = "TD",
    theme = "github", show_artifacts = FALSE, show_source_info = FALSE,
    enable_clicks = FALSE, click_protocol = "vscode", palette = NULL,
    style_nodes = TRUE, node_labels = "label", title = NULL)
```

**`put_theme()`**:
```r
put_theme(base = "light", input = NULL, process = NULL, output = NULL,
    decision = NULL, artifact = NULL, start = NULL, end = NULL)
# Each node type: c(fill = "#hex", stroke = "#hex", color = "#hex")
```

## Common Patterns

**Basic**
```r
put("./src/") |> put_diagram()
```

**Customize**
```r
put_diagram(wf, theme = "dark", direction = "LR")
put_diagram(wf, show_artifacts = FALSE)       # Hide data files
put_diagram(wf, show_source_info = TRUE)      # Show file info
put_diagram(wf, palette = put_theme(base = "dark", input = c(fill = "#1a5276")))
```

**Save**
```r
put_diagram(wf, output = "file", file = "workflow.md")
put_diagram(wf, output = "clipboard")
mermaid_code <- put_diagram(wf, output = "raw")
```

**Exclude files**
```r
put("./src/", exclude = "test")
put_auto("./", exclude = c("vendor", "fixture"))
```

**Debug**
```r
put("./", log_level = "DEBUG")
```

## Configuration & Utilities

| Function | Purpose | Example |
|----------|---------|---------|
| `get_comment_prefix()` | Comment prefix for extension | `get_comment_prefix("sql")` → `"--"` |
| `get_supported_extensions()` | All supported extensions | `get_supported_extensions()` |
| `list_supported_languages()` | Supported languages | `list_supported_languages(detection_only = TRUE)` |
| `get_detection_patterns()` | Auto-detection patterns | `get_detection_patterns("r", type = "input")` |
| `get_diagram_themes()` | Available themes | `get_diagram_themes()` |
| `is_valid_put_annotation()` | Validate syntax | `is_valid_put_annotation('# put label:"X"')` |
| `set_putior_log_level()` | Set logging level | `set_putior_log_level("DEBUG")` |
| `run_sandbox()` | Launch Shiny sandbox | `run_sandbox()` |

## Themes and Direction

| Theme | Use Case |
|-------|----------|
| `light` | Bright colors (default) |
| `dark` | Dark mode UIs |
| `minimal` | Print-friendly, grayscale |
| `github` | README files |
| `viridis` | Colorblind-safe (purple-blue-green-yellow) |
| `magma` | Colorblind-safe warm (purple-red-yellow) |
| `plasma` | Colorblind-safe vibrant (purple-pink-yellow) |
| `cividis` | Maximum accessibility (blue-yellow only) |

**Directions**: `TD` (default), `LR`, `BT`, `RL`

## Node Types

| Type | Shape | Use For |
|------|-------|---------|
| `input` | Stadium | Data loading |
| `process` | Rectangle | Transformations (default) |
| `output` | Subroutine | Reports, exports |
| `decision` | Diamond | Conditional logic |
| `start` | Stadium | Workflow entry point |
| `end` | Stadium | Workflow exit point |
| `artifact` | Cylinder | Data files (auto-created) |

```{r node-shapes, echo=FALSE, results='asis', eval=TRUE}
library(putior)
shapes_workflow <- data.frame(
  file_name = rep("example.R", 4),
  id = c("load", "transform", "export", "check"),
  label = c("input", "process", "output", "decision"),
  node_type = c("input", "process", "output", "decision"),
  input = c(NA, "a", "b", "b"),
  output = c("a", "b", "c", "d"),
  stringsAsFactors = FALSE
)
cat("```mermaid\n")
cat(put_diagram(shapes_workflow, theme = "github", show_artifacts = FALSE, output = "raw"))
cat("\n```\n")
```

## See Also

| Guide | Description |
|-------|-------------|
| [Quick Start](quick-start.html) | First diagram in 2 minutes |
| [Annotation Guide](annotation-guide.html) | Complete syntax reference |
| [Features Tour](features-tour.html) | Auto-detection, themes, logging |
| [API Reference](api-reference.html) | Function documentation |
| [Showcase](showcase.html) | Real-world examples |
| [Troubleshooting](troubleshooting.html) | Common issues and solutions |
| [AI Integration](ai-integration.html) | MCP/ACP integration guide |