Quick Start

Your First Diagram in 2 Minutes

Step 1: Install

install.packages("putior")

library(putior)

Step 2: Add Annotations to Your Code

Add # put comments to your R scripts:

# my_analysis.R
# put label:"Load Data", output:"raw_data"
data <- read.csv("sales.csv")

# put label:"Clean Data", input:"raw_data", output:"clean_data"
clean <- data[complete.cases(data), ]

# put label:"Generate Report", input:"clean_data", output:"report.html"
rmarkdown::render("report.Rmd")

Step 3: Generate Diagram

workflow <- put("my_analysis.R")
put_diagram(workflow)

That’s it! You’ll see a flowchart like this:

flowchart TD
    load(["Load Data"])
    clean["Clean Data"]
    report[["Generate Report"]]

    %% Connections
    load --> clean
    clean --> report

    %% Styling
    classDef inputStyle fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e40af
    class load inputStyle
    classDef processStyle fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#5b21b6
    class clean processStyle
    classDef outputStyle fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#15803d
    class report outputStyle

---

Try It Now

# Create a temporary file with annotations
temp_file <- tempfile(fileext = ".R")
writeLines(c(
  '# put label:"Extract", output:"raw.csv"',
  'data <- read.csv("source.csv")',
  '',
  '# put label:"Transform", input:"raw.csv", output:"clean.csv"',
  'clean <- transform(data)',
  '',
  '# put label:"Load", input:"clean.csv", output:"database"',
  'write_to_db(clean)'
), temp_file)

# Scan and visualize
workflow <- put(temp_file)
#> Warning: Validation issues in file23f262bc7354.R line 7:
#> File reference missing extension: database

cat("```mermaid\n")

``` r
cat(put_diagram(workflow, output = "raw"))

flowchart TD aecf4ce1_93bb_48cb_91e7_a04a3cdf97c4[“Extract”] c55b7048_25ff_489c_b854_7f6638d36a76[“Transform”] node_2da9c10f_5f4c_4efb_852d_5214339d69c9[“Load”]

%% Connections
aecf4ce1_93bb_48cb_91e7_a04a3cdf97c4 --> c55b7048_25ff_489c_b854_7f6638d36a76
c55b7048_25ff_489c_b854_7f6638d36a76 --> node_2da9c10f_5f4c_4efb_852d_5214339d69c9

cat("\n```\n")

Cleanup

unlink(temp_file)

---
## Annotation Syntax at a Glance

put label:“Step Name”, input:“file.csv”, output:“result.csv”

| Field | Purpose | Required |
|-------|---------|----------|
| `label` | Human-readable name | Yes |
| `input` | Files/data consumed | No |
| `output` | Files/data produced | No |
| `id` | Unique identifier | No (auto-generated) |
| `node_type` | `input`, `process`, `output`, `decision`, `start`, `end` | No (defaults to `process`) |

**Multiple inputs/outputs:** Use commas: `input:"a.csv, b.csv"`

---

## Multi-Language Support

putior works with 30+ languages. Comment prefix is auto-detected:

| Language | Annotation |
|----------|------------|
| R, Python, Shell | `# put label:"..."` |
| SQL, Lua | `-- put label:"..."` |
| JavaScript, Go, Rust | `// put label:"..."` |
| MATLAB | `% put label:"..."` |

---

## Common Patterns

### Scan a Directory

``` r
workflow <- put("./src/")
put_diagram(workflow)

Include Subdirectories

workflow <- put("./project/", recursive = TRUE)

Auto-Detect Workflow (No Annotations!)

# Automatically detect file I/O from code
workflow <- put_auto("./src/")
put_diagram(workflow)

Choose a Theme

put_diagram(workflow, theme = "github")  # or: light, dark, minimal, viridis

Save to File

put_diagram(workflow, output = "file", file = "workflow.md")

---

Interactive Sandbox

Experiment without creating files:

run_sandbox()  # Opens Shiny app

---

What’s Next?

Guide	When to Read
Annotation Guide	Complete syntax reference, multiline annotations, best practices
Quick Reference	Printable cheat sheet for daily use
Features Tour	Auto-detection, logging, interactive diagrams, metadata display
API Reference	All functions and parameters
Showcase	Real-world examples (ETL, ML pipelines, bioinformatics)
Troubleshooting	Common issues and solutions

---

Quick Reference

# Core functions
put(path)                    # Extract annotations
put_diagram(workflow)        # Generate Mermaid diagram
put_auto(path)               # Auto-detect workflow (no annotations)
put_generate(path)           # Generate annotation suggestions

# Useful options
put("./", recursive = TRUE)  # Include subdirectories
put_diagram(wf, theme = "github", direction = "LR")
put_diagram(wf, show_artifacts = FALSE)  # Hide data files

Need help? Run ?put or ?put_diagram for full documentation.