Oak SCSS Parser

A high-performance SCSS parser for Rust, built with the Oak parser combinator framework. Parse Sassy CSS stylesheets with comprehensive AST generation and error handling.

Overview

Oak SCSS provides robust parsing capabilities for SCSS stylesheet files, supporting variables, mixins, functions, nesting, and all major SCSS constructs. Built on the Oak parser combinator framework, it delivers excellent performance and detailed error messages.

Features

• ✅ Complete SCSS Support: Parse variables, mixins, functions, nesting, and imports
• ✅ Modern Rust API: Type-safe parsing with comprehensive error handling
• ✅ High Performance: Built on the efficient Oak parser combinator framework
• ✅ Rich AST: Detailed Abstract Syntax Tree with source location tracking
• ✅ Extensible: Easy to extend for custom SCSS dialects
• ✅ Well Tested: Comprehensive test suite with real-world examples

Quick Start

Parsing Examples

Basic SCSS Parsing

use oak::{Parser, Language};
use oak_scss::SCSSLanguage;

fn main() {
    let source = r#"
        $primary-color: #3498db;
        $secondary-color: #2ecc71;
        $font-size: 16px;
        
        .button {
            background-color: $primary-color;
            color: white;
            padding: 10px 20px;
            border-radius: 5px;
            
            &:hover {
                background-color: darken($primary-color, 10%);
            }
            
            &.large {
                font-size: $font-size * 1.2;
                padding: 15px 30px;
            }
        }
    "#;
    
    let mut parser = Parser::<SCSSLanguage>::new();
    match parser.parse(&source) {
        Ok(ast) => {
            println!("Parsed AST: {:#?}", ast);
        }
        Err(error) => {
            eprintln!("Parse error: {}", error);
        }
    }
}

Advanced Mixins and Functions

use oak::{Parser, Language};
use oak_scss::SCSSLanguage;

fn main() {
    let source = r#"
        @mixin flex-center {
            display: flex;
            justify-content: center;
            align-items: center;
        }
        
        @function rem($pixels, $base: 16px) {
            @return $pixels / $base * 1rem;
        }
        
        @mixin responsive-font($min-size, $max-size, $min-width: 320px, $max-width: 1200px) {
            font-size: $min-size;
            
            @media screen and (min-width: $min-width) {
                font-size: calc(#{$min-size} + #{strip-unit($max-size - $min-size)} * 
                    ((100vw - #{$min-width}) / #{strip-unit($max-width - $min-width)}));
            }
            
            @media screen and (min-width: $max-width) {
                font-size: $max-size;
            }
        }
        
        .container {
            @include flex-center;
            min-height: 100vh;
            
            .content {
                @include responsive-font(14px, 24px);
                padding: rem(20px);
                max-width: rem(800px);
            }
        }
    "#;
    
    let mut parser = Parser::<SCSSLanguage>::new();
    match parser.parse(&source) {
        Ok(ast) => {
            println!("Advanced SCSS parsed successfully!");
        }
        Err(error) => {
            eprintln!("Parse error: {}", error);
        }
    }
}

Advanced Features

Nested Imports

Oak SCSS supports parsing nested imports:

let source = r#"
    @import 'variables';
    @import 'mixins';
    
    @import url('https://fonts.googleapis.com/css?family=Roboto');
"#;

Control Directives

Parse control directives like @if, @for, @each, and @while:

let source = r#"
    @for $i from 1 through 12 {
        .col-#{$i} {
            width: percentage($i / 12);
        }
    }
    
    @each $color in red, green, blue {
        .bg-#{$color} {
            background-color: $color;
        }
    }
"#;

AST Structure

The parser generates a rich AST with the following main node types:

• SCSSFile - Root node containing the entire file
• Variable - Variable declarations and references
• Rule - CSS rules with selectors and declarations
• Mixin - Mixin definitions and includes
• Function - Function definitions and calls
• Import - Import statements
• Media - Media queries and blocks
• Expression - SCSS expressions and operations
• AtRule - At-rules like @extend, @debug, @warn

Performance

Oak SCSS is designed for high performance:

• Zero-copy parsing where possible
• Streaming support for large stylesheet files
• Efficient memory usage with minimal allocations
• Fast error recovery for better developer experience

Integration

Oak SCSS integrates seamlessly with the Oak ecosystem:

use oak::{Parser, Language};
use oak_scss::SCSSLanguage;

// Use with other Oak parsers
let mut parser = Parser::<SCSSLanguage>::new();
let result = parser.parse(scss_source);

Examples

More examples can be found in the examples directory:

• Basic SCSS parsing
• Variables and mixins
• Nested selectors
• Functions and operations
• Error handling

Contributing

We welcome contributions! Please see our Contributing Guide for details.