fop-cli-0.1.1 is not a library.

FOP CLI - Apache FOP Command-Line Interface

A high-performance command-line tool for converting XSL-FO documents to multiple output formats including PDF, SVG, PostScript, PNG, JPEG, and plain text.

Part of the COOLJAPAN FOP ecosystem — an Apache FOP-compatible pure-Rust implementation.

Features

Fast conversion — Rust-based implementation for optimal performance
Multiple output formats — PDF, SVG, PostScript, PNG, JPEG, and plain text
Progress reporting — Real-time progress bars for large documents
Statistics — Detailed processing metrics and timing (text or JSON)
Validation — Validate XSL-FO documents without generating output
PDF encryption — Owner/user password protection and permission control
Flexible options — Support for custom fonts, images, and PDF metadata
Apache FOP-compatible — Drop-in replacement CLI interface

Installation

From Source

cargo install --path crates/fop-cli

From Workspace

cargo build --release --package fop-cli
cp target/release/fop /usr/local/bin/

Usage

Basic Conversion

fop input.fo output.pdf

Output to Different Formats

# PDF (default)
fop input.fo output.pdf

# SVG
fop input.fo output.svg

# PostScript
fop input.fo output.ps

# PNG
fop input.fo output.png

# JPEG
fop input.fo output.jpg

# Plain text
fop input.fo output.txt

With Progress and Statistics

fop input.fo output.pdf --stats

Validation Only

fop input.fo --validate-only

Verbose Output

fop input.fo output.pdf --verbose

Custom Resources

fop input.fo output.pdf \
    --images-dir ./images \
    --font-dir ./fonts

PDF Metadata

fop input.fo output.pdf \
    --title "My Document" \
    --author "John Doe" \
    --subject "Technical Report" \
    --keywords "fop, pdf, xsl-fo"

PDF Encryption

# Set owner and user passwords
fop input.fo output.pdf \
    -o "owner-secret" \
    -u "user-secret"

# Restrict permissions
fop input.fo output.pdf \
    -o "owner-secret" \
    --noprint \
    --nocopy \
    --noedit \
    --noannotations

Advanced Options

fop input.fo output.pdf \
    --compress \
    --pdf-version 1.7 \
    --jobs 4 \
    --strict

Command-Line Options

Input/Output

<INPUT> — Input XSL-FO file (required)
[OUTPUT] — Output file (optional with --validate-only)

Processing Options

-v, --verbose — Enable verbose logging
--stats — Show detailed statistics after conversion
--validate-only — Only validate the XSL-FO document
-q, --quiet — Suppress progress bars and animations
--no-progress — Disable progress reporting (for scripting)

Resources

--images-dir <DIR> — Directory containing images
--font-dir <DIR> — Directory containing fonts

PDF Options

--compress — Enable PDF compression (reduces file size)
--pdf-version <VERSION> — PDF version (1.4, 1.5, 1.6, 1.7, 2.0) [default: 1.4]
--author <AUTHOR> — Set PDF author metadata
--title <TITLE> — Set PDF title metadata
--subject <SUBJECT> — Set PDF subject metadata
--keywords <KEYWORDS> — Set PDF keywords metadata

Encryption Options

-o, --owner-password <PASSWORD> — Set PDF owner password (full access)
-u, --user-password <PASSWORD> — Set PDF user password (restricted access)
--noprint — Disallow printing
--nocopy — Disallow copying content
--noedit — Disallow editing
--noannotations — Disallow adding annotations

Performance

-j, --jobs <N> — Number of threads to use (default: auto-detect)
--max-memory <MB> — Maximum memory usage in MB

Validation

--strict — Enable strict XSL-FO validation
--fail-fast — Stop processing after first error

Output Format

--output-format <FORMAT> — Output format for validation results (text, json) [default: text]

Examples

Basic Document Conversion

# Simple conversion
fop document.fo document.pdf

# With progress and stats
fop document.fo document.pdf --stats

Large Document Processing

# Show progress for large documents
fop large-report.fo large-report.pdf --verbose --stats

# Use multiple threads
fop large-report.fo large-report.pdf -j 8

Validation Workflow

# Validate before generating
fop document.fo --validate-only

# If valid, generate PDF
fop document.fo document.pdf

Scripting Integration

# Disable progress bars for scripts
fop document.fo document.pdf --quiet --stats --output-format json > stats.json

# Exit code indicates success (0) or failure (non-zero)
if fop document.fo document.pdf --quiet; then
    echo "Success"
else
    echo "Failed"
fi

Production Deployment

# Compressed PDF with metadata and encryption
fop report.fo report.pdf \
    --compress \
    --pdf-version 1.7 \
    --title "Annual Report 2024" \
    --author "Acme Corporation" \
    --subject "Financial Report" \
    --keywords "finance, annual, 2024" \
    -o "owner-secret" \
    -u "reader-pass" \
    --noprint --nocopy

Multi-Format Output

# Generate multiple formats from the same source
fop document.fo document.pdf
fop document.fo document.svg
fop document.fo document.ps
fop document.fo document.txt

Output

Progress Output

Apache FOP
Rust Implementation

✓ Read input file: document.fo (5ms)
✓ Parsed FO tree (1243 nodes) (245ms)
✓ Layout complete (3456 areas) (1.2s)
✓ PDF rendered (42 pages) (890ms)
✓ Saved to document.pdf (15ms)

✓ Success!

  Input:   document.fo
  Output:  document.pdf
  Size:    234.5 KB → 1.2 MB
  Pages:   42
  Time:    2.35s

Statistics Output (Text)

Processing Statistics:

  ⚙️ Parsing:      245ms
  ⚙️ Layout:       1.20s
  ⚙️ Rendering:    890ms
  ✨ Total:        2.35s

  • FO Nodes:     1243
  • Areas:        3456
  📄 Pages:        42

  Input size:    234.5 KB
  Output size:   1.2 MB
  Size ratio:    5.12x

  Throughput:    17.87 pages/sec

Statistics Output (JSON)

{
  "parsing": {
    "duration_ms": 245,
    "nodes": 1243
  },
  "layout": {
    "duration_ms": 1200,
    "areas": 3456
  },
  "rendering": {
    "duration_ms": 890,
    "pages": 42
  },
  "total": {
    "duration_ms": 2350,
    "input_bytes": 240128,
    "output_bytes": 1258291,
    "warnings": 0,
    "errors": 0
  }
}

Performance Tips

For Large Documents

Use multiple threads: -j 8 (adjust based on CPU cores)
Enable compression: --compress (reduces output size)
Suppress progress: --quiet (slight performance gain)

For Batch Processing

#!/bin/bash
for fo_file in *.fo; do
    pdf_file="${fo_file%.fo}.pdf"
    fop "$fo_file" "$pdf_file" --quiet --compress
done

For CI/CD Pipelines

# Example GitHub Actions workflow
- name: Generate PDF
  run: |
    fop document.fo document.pdf \
      --quiet \
      --fail-fast \
      --stats \
      --output-format json > stats.json

Error Handling

The CLI returns different exit codes:

0 — Success
1 — Error (parsing, layout, rendering, or I/O)

Errors are printed to stderr with detailed context:

Error: Failed to parse XSL-FO document

Caused by:
  0: Unexpected element: fo:invalid-element
  1: Line 42, column 5

Logging

Set RUST_LOG environment variable for fine-grained control:

# Debug all FOP modules
RUST_LOG=debug fop document.fo document.pdf

# Only show errors
RUST_LOG=error fop document.fo document.pdf

# Module-specific logging
RUST_LOG=fop_core=debug,fop_layout=info fop document.fo document.pdf

Building

# Debug build
cargo build --package fop-cli

# Release build (optimized)
cargo build --release --package fop-cli

# Run tests
cargo test --package fop-cli

# Run clippy
cargo clippy --package fop-cli -- -D warnings

Dependencies

Crate	Version	Purpose
`fop-core`	workspace	FO tree parsing and processing
`fop-layout`	workspace	Page layout engine
`fop-render`	workspace	Multi-format rendering
`fop-types`	workspace	Shared types and data structures
`clap`	4.5	Command-line argument parsing
`anyhow`	1.0	Error handling
`indicatif`	0.18	Progress bars
`console`	0.16	Terminal styling
`humantime`	2.3	Human-readable durations
`bytesize`	2.3	Human-readable byte sizes
`serde_json`	1.0	JSON statistics output
`env_logger`	0.11	Logging backend
`log`	0.4	Logging facade

Related Crates

Crate	Description
`fop-core`	XSL-FO tree parsing and validation
`fop-layout`	Page layout and area tree generation
`fop-render`	Multi-format rendering (PDF, SVG, PS, PNG, JPEG, Text)
`fop-types`	Shared FO types, properties, and data structures
`fop-pdf-renderer`	Low-level PDF generation with encryption support
`fop-wasm`	WebAssembly bindings for browser usage
`fop-python`	Python bindings via PyO3

License

Apache License 2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

fop-cli 0.1.1