webpage_quality_analyzer 1.0.2

# Examples Directory

This directory contains comprehensive examples demonstrating all functionality of the webpage quality analyzer API.

## Example Files

### 🚀 **Level 1 API - Simple Usage**
- **File:** `level1_simple_usage.rs`
- **Purpose:** Demonstrates the simplest API usage with `analyze()` and `analyze_with_profile()` functions
- **Use Cases:** Quick analysis, prototyping, simple integrations
- **Key Features:**
  - Basic URL analysis with automatic HTML fetching
  - HTML content analysis without network requests
  - Profile-specific analysis (content_article, news, blog, product)
  - Basic error handling patterns

### ⚙️ **Level 2 API - Builder Pattern**
- **File:** `level2_builder_pattern.rs`
- **Purpose:** Shows configurable analysis using the builder pattern
- **Use Cases:** Applications needing fine-grained control over analysis parameters
- **Key Features:**
  - Customizable analyzer configuration
  - Feature toggles (NLP, link checking)
  - Multiple analyzer instances
  - Detailed metrics access

### 📋 **Level 3 API - Configuration Files**
- **File:** `level3_config_files.rs`
- **Purpose:** Demonstrates advanced configuration using external config files
- **Use Cases:** Enterprise applications, complex scoring requirements
- **Key Features:**
  - YAML, JSON, and TOML configuration support
  - Custom scoring profiles
  - Configuration comparison
  - Team-shareable configurations

### 🚀 **Advanced Features**
- **File:** `advanced_features.rs`
- **Purpose:** Showcases specialized functionality and advanced capabilities
- **Use Cases:** Applications requiring comprehensive analysis
- **Key Features:**
  - NLP processing and language detection
  - Link checking and validation
  - Edge case handling
  - Batch processing patterns
  - Comprehensive report analysis

### 🌍 **Real-World Use Cases**
- **File:** `real_world_use_cases.rs`
- **Purpose:** Practical applications in different business contexts
- **Use Cases:** SEO auditing, content quality assessment, competitive analysis
- **Key Features:**
  - SEO audit workflows
  - Content quality evaluation
  - Competitive benchmarking
  - Quality monitoring over time

### 📚 **Comprehensive API Reference**
- **File:** `comprehensive_api_reference.rs`
- **Purpose:** Complete reference for all available API methods and configurations
- **Use Cases:** Developer reference, API exploration
- **Key Features:**
  - All public functions demonstrated
  - Complete report structure breakdown
  - Error handling patterns
  - Configuration options reference

### ⚡ **Performance Optimization**
- **File:** `performance_optimization.rs`
- **Purpose:** Performance best practices and optimization techniques
- **Use Cases:** High-throughput applications, performance-critical scenarios
- **Key Features:**
  - Performance benchmarking
  - Batch processing optimization
  - Memory usage optimization
  - Configuration tuning for different use cases

## Running the Examples

Each example can be run independently using Cargo:

```bash
# Run Level 1 simple usage examples
cargo run --example level1_simple_usage

# Run Level 2 builder pattern examples
cargo run --example level2_builder_pattern

# Run Level 3 configuration file examples
cargo run --example level3_config_files

# Run advanced features examples
cargo run --example advanced_features

# Run real-world use cases
cargo run --example real_world_use_cases

# Run comprehensive API reference
cargo run --example comprehensive_api_reference

# Run performance optimization examples
cargo run --example performance_optimization
```

## Example Output

Each example provides detailed output showing:
- ✅ Successful operations with scores and metrics
- ❌ Error handling demonstrations
- 📊 Detailed analysis results
- 💡 Best practices and recommendations
- 🎯 Use case specific optimizations

## API Quick Reference

### Core Functions
```rust
// Level 1: Simple usage
let report = analyze("https://example.com", None).await?;
let report = analyze_with_profile("https://example.com", None, "news").await?;

// Level 2: Builder pattern
let analyzer = Analyzer::builder()
    .with_profile_name("content_article")?
    .enable_nlp(true)
    .enable_linkcheck(true)
    .build()?;
let report = analyzer.run("https://example.com", None).await?;

// Level 3: Configuration files
let analyzer = from_config_file("config.yaml")?;
let report = analyzer.run("https://example.com", None).await?;
```

### Available Profiles
- `content_article` - Long-form articles and blog posts (default)
- `news` - News articles and timely content
- `blog` - Personal blogs and informal content
- `product` - Product pages and e-commerce content

### Builder Options
- `with_profile_name(name)` - Set scoring profile
- `enable_linkcheck(bool)` - Enable/disable link validation
- `linkcheck_sample(size)` - Set number of links to check
- `enable_nlp(bool)` - Enable/disable NLP features
- `add_report(bool)` - Include/exclude detailed report data

### Error Types
- `InvalidUrl` - URL validation errors
- `InvalidProfile` - Profile configuration errors
- `ParseError` - HTML parsing errors
- `NetworkError` - Network/HTTP errors
- `ConfigError` - Configuration file errors

## Best Practices

1. **Performance:**
   - Reuse analyzer instances for better performance
   - Disable unused features (NLP, link checking) for speed
   - Use minimal reporting for high-throughput scenarios

2. **Error Handling:**
   - Always handle `Result<T, AnalyzeError>` properly
   - Implement retry logic for network errors
   - Validate inputs before processing

3. **Configuration:**
   - Choose appropriate profiles for your content type
   - Use configuration files for complex setups
   - Test configurations with representative content

4. **Memory Management:**
   - Use `add_report(false)` to reduce memory usage
   - Process large documents in batches
   - Clear or reuse variables in long-running applications

## Contributing

When adding new examples:
1. Follow the established naming convention (`category_description.rs`)
2. Include comprehensive documentation and comments
3. Demonstrate both success and error cases
4. Provide practical, real-world scenarios
5. Include performance considerations where relevant

## Support

For questions about the examples or API usage:
- Check the comprehensive API reference example
- Review the real-world use cases for practical patterns
- Examine the performance optimization guide for best practices
- Refer to the main project documentation