paperformatter/README.md

# Paper Formatter

A Go library that converts JSON files containing paper reviews into formatted Markdown documents. The library organizes papers into accepted and rejected categories, formatting each entry with title, arXiv link, abstract, decision, and explanation.

## Installation

```bash
go get gitea.r8z.us/stwhite/paperformatter
```

## Usage

```go
import "gitea.r8z.us/stwhite/paperformatter"

err := paperformatter.FormatPapers("input.json", "output.md")
if err != nil {
    log.Fatal(err)
}
```

## Input Format

The library supports two JSON input formats:

### Format 1: Direct Array
```json
[
  {
    "paper": {
      "title": "Paper Title",
      "abstract": "Paper Abstract",
      "arxiv_id": "2301.00000"
    },
    "decision": "accept",
    "explanation": "Explanation for the decision"
  }
]
```

### Format 2: Categorized Object
```json
{
  "accepted": [
    {
      "paper": {
        "title": "Paper Title",
        "abstract": "Paper Abstract",
        "arxiv_id": "2301.00000"
      },
      "decision": "accept",
      "explanation": "Explanation for the decision"
    }
  ],
  "rejected": [
    {
      "paper": {
        "title": "Another Paper",
        "abstract": "Another Abstract",
        "arxiv_id": "2301.00001"
      },
      "decision": "reject",
      "explanation": "Explanation for rejection"
    }
  ]
}
```

Both formats support the same entry structure, with each entry containing:
- A paper object with title, abstract, and arXiv ID
- A decision (accept/reject, case-insensitive)
- An explanation for the decision

## Output Format

The library generates a Markdown file that:
1. Separates papers into "Accepted Papers" and "Rejected Papers" sections
2. For each paper, includes:
   - Title as a heading
   - ArXiv link
   - Abstract (formatted as a blockquote)
   - Decision
   - Explanation for the decision

Example output:

```markdown
# Accepted Papers

## Example Paper Title

[arXiv:2301.00000](https://arxiv.org/abs/2301.00000)

> This is the paper's abstract...

**Decision:** accept

**Explanation:** This is the explanation for accepting the paper...

# Rejected Papers

[Additional papers would be listed here...]
```

## Error Handling

The library provides detailed error handling with custom error types:

### Validation Errors
- Empty or missing required fields (title, abstract, arxiv_id)
- Invalid decision values (must be "accept" or "reject")
- Empty explanation

### File Operation Errors
- Input file cannot be read
- Output file cannot be written
- Includes detailed information about the failed operation and file path

### JSON Parsing Errors
- Invalid JSON format
- Missing required fields in JSON structure

Each error type provides specific information about what went wrong:
```go
// Example error handling
err := paperformatter.FormatPapers("input.json", "output.md")
if err != nil {
    switch e := err.(type) {
    case *paperformatter.ValidationError:
        fmt.Printf("Validation failed for %s: %s\n", e.Field, e.Message)
    case *paperformatter.FileError:
        fmt.Printf("File operation '%s' failed for '%s': %v\n", e.Op, e.Path, e.Wrapped)
    case *paperformatter.JSONError:
        fmt.Printf("JSON parsing failed: %v\n", e.Wrapped)
    default:
        fmt.Printf("Error: %v\n", err)
    }
}
```

## Requirements

- Go 1.23.1 or later

## Testing

The library includes comprehensive unit tests covering:
- Successful format conversion
- Error handling cases
- Edge cases (empty input, case sensitivity)
- File I/O operations
- Multiline text formatting

Run the tests using:
```bash
go test -v
```