yass-css 0.1.0-x86_64-linux → 0.2.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea34c5802afae12c1fb031904b416c2797dbe07ee058253b7c4f2bb05665612f
-  data.tar.gz: d0e64ec23a442d7a11bfd9c73052dd90d5b5304f334ff6410f61f3ad28ae1029
+  metadata.gz: b67d47c573422d558b9b6c7635c76e9d385172d38e8ec602f53357ba069c1a62
+  data.tar.gz: 0e8cd4ea4be36be0a931deea9a7e4c329b3307b8bf12465aebbb9973124aaa65
 SHA512:
-  metadata.gz: b820356ab0bc5578affdf588f6af5f32fc1c6ddbbb2e2df1b53d7ebe9d24fa39c05c1aa114875a5f31ab2c1b00b031e6320aabcd1bb69d6860438152d3bd6143
-  data.tar.gz: 503f5fe900d8e8c1e45f0fff2693205fd8586eb07316749acd59eb47718140334c728a23fe7dd1ecd3b264709cda5a50f1ca133ca8cea5fe772efe769d20b502
+  metadata.gz: eb063f0f79ff8aa9d7ac106fadd39fa08d54f398b466a575b1dd17ebef878bbe332bcbb8e33c15dde4b47b8306a3724c089f007e7e837deb30f1eb8c8943850d
+  data.tar.gz: 8e7df3c260bdebeeedc1c13be81dccff6303f73cd8c5dead6516fed50f4129863113702601e7ccc805f489c9797f0ab647babeb6d1f1f55938b4e822cbe945bd

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
-## [0.1.0] - 2026-03-25
+## [0.2.0] - 2026-04-19
+
+- Fully support all style declarations.
+- Add support for `@media` rules.
+- Add support for `@font-face` rules.
+
+## [0.1.0] - 2026-03-26
 
 - Initial release

data/README.md

@@ -1,38 +1,134 @@
 # Yass
 
-TODO: Delete this and the text below, and describe your gem
+Yass is a Ruby wrapper around the [Stylo](https://github.com/servo/stylo) CSS engine, the parser behind the Firefox and Servo browsers developed by Mozilla.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/yass`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Rationale
 
-## Installation
+I needed a CSS parser in Ruby but couldn't find one that could handle nested CSS rules. Stylo was born out of that need, and aims to be a complete CSS parser for Ruby, covering the entire CSS spec.
+
+Stylo is itself under active development, and Yass does not yet wrap the entire Stylo API. If Yass doesn't support a feature you need, consider adding the missing functionality and submitting a pull request.
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add yass-css
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install yass-css
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+There are two main ways to use Yass: by navigating the object hierarchy by hand, or by using the visitor pattern.
+
+By "navigating the object hierarchy," I just mean "calling methods on objects." Here's an example.
+
+```ruby
+require "yass"
+
+sheet = Yass::Parser.parse(<<~CSS)
+  h1 {
+    align-items: center;
+    display: flex;
+    position: absolute;
+  }
+CSS
+
+# this is the whole h1 { ... } rule
+first_rule = sheet.rules.first
+puts first_rule.class  # => Yass::StyleRule
+
+# this is the h1 selector
+first_selector = first_rule.selectors.first.children.first
+puts first_selector.value  # => "h1"
+```
+
+The entire object hierarchy can be discovered by dropping into a console session (via `bin/console`) and playing around.
+
+### The Visitor Pattern
+
+Yass also comes with a `Yass::Visitor` class that implements the [visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern).
+
+Some people love the visitor pattern, and some people seem to hate it. If you're in the second camp, feel free to skip this section.
+
+Visitor classes contain `visit_*` methods that the library calls in-order as it traverses the object hierarchy contained within a parsed stylesheet. The methods the visitor supports can be examined by reading the code in lib/yass/visitor.rb.
+
+Let's write a visitor class that prints all the class names in the given stylesheet:
+
+```ruby
+class MyVisitor < Yass::Visitor
+  def visit_selector_klass(node)
+    # node is an instance of Yass::Selector::Klass
+    puts node.value
+  end
+end
+```
+
+Now we can use our visitor to visit a stylesheet:
+
+```ruby
+sheet = Yass::Parser.parse(<<~CSS)
+  .left {
+    float: left;
+  }
+
+  .right {
+    float: right;
+  }
+CSS
+
+visitor = MyVisitor.new
+
+# this will result in "left" and "right" being printed to stdout
+visitor.visit(sheet)
+```
+
+## Examples
+
+For more examples, see the examples/ directory.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake` to compile the native extension and run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Running Tests
+
+Simply execute:
+
+```bash
+bundle exec rake
+```
+
+This will compile the native extension and run the tests immediately afterwards. To compile only, run:
+
+```bash
+bundle exec rake compile
+```
+
+To run the tests only, run:
+
+```bash
+bundle exec rake spec
+```
+
+To run the full test suite (much slower) that attempts to parse the ~33k example CSS files from the [Web Platform Test (WPT) suite](https://github.com/web-platform-tests/wpt), run:
+
+```ruby
+bundle exec rake spec:full
+```
+
+## Releasing
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Releasing Yass is done by creating a new release on GitHub. Doing so will trigger a special CI job capable of building the native extension for all supported plaforms and publishing a "fat" .gem file to rubygems.org.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/yass. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/yass/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/camertron/yass. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/camertron/yass/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -40,4 +136,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Yass project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/yass/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Yass project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/camertron/yass/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -25,6 +25,15 @@ end
 
 task default: %i[compile spec]
 
+namespace :spec do
+  desc 'Run full specs suit'
+  task full: [:full_spec_env, :compile, :spec]
+
+  task :full_spec_env do
+    ENV['FULL_SPEC'] = 'true'
+  end
+end
+
 # For whatever reason, the :native task that comes with rb-sys doesn't work, so
 # we define our own
 task :native, [:platform] do |task, args|
@@ -45,3 +54,77 @@ task :native, [:platform] do |task, args|
 
   sh(env, "bundle", "exec", "rb-sys-dock", "--platform", args[:platform], "--build")
 end
+
+task :codegen do
+  require "yass"
+  require_relative "codegen/rust_file_set"
+
+  general_files = Yass::Codegen::RustFileSet::new(
+    Dir.glob("ext/yass/src/general/**/*.rs")
+  )
+
+  File.write("lib/yass/general.rb", <<~RUBY)
+    # frozen_string_literal: true
+
+    #{general_files.module_tree.to_ruby_classes}
+  RUBY
+
+  declaration_files = Yass::Codegen::RustFileSet.new(Dir.glob("ext/yass/src/declarations/**/*.rs"))
+
+  File.write("lib/yass/declarations.rb", <<~RUBY)
+    # frozen_string_literal: true
+
+    #{declaration_files.module_tree.to_ruby_classes}
+  RUBY
+
+  selector_files = Yass::Codegen::RustFileSet.new(Dir.glob("ext/yass/src/selectors/**/*.rs"))
+
+  File.write("lib/yass/selectors.rb", <<~RUBY)
+    # frozen_string_literal: true
+
+    #{selector_files.module_tree.to_ruby_classes}
+  RUBY
+
+  rule_files = Yass::Codegen::RustFileSet.new([
+    "ext/yass/src/rules/rule.rs",
+    "ext/yass/src/rules/style_rule.rs",
+    "ext/yass/src/rules/media_rule.rs",
+    "ext/yass/src/rules/font_face_rule.rs",
+    *Dir.glob("ext/yass/src/rules/fonts/**/*.rs"),
+  ])
+
+  File.write("lib/yass/rules.rb", <<~RUBY)
+    # frozen_string_literal: true
+
+    #{rule_files.module_tree.to_ruby_classes}
+  RUBY
+
+  all_modules = general_files.module_tree
+    .merge(declaration_files.module_tree)
+    .merge(selector_files.module_tree)
+    .merge(rule_files.module_tree)
+
+  visitor_class = <<~RUBY
+    # frozen_string_literal: true
+
+    module Yass
+      class Visitor
+        def visit(node)
+          node.accept(self) if node
+        end
+
+        def visit_list(nodes)
+          nodes.each { |node| visit(node) }
+        end
+
+        def visit_stylesheet(node)
+          visit_list(node.rules)
+        end
+
+    #{all_modules.to_visitor_methods(indent: "    ").join("\n")}
+      end
+    end
+  RUBY
+
+  File.write("lib/yass/visitor.rb", visitor_class)
+end

data/codegen/ruby_module_tree.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "utils"
+
+module Yass
+  module Codegen
+    class RubyModule
+      attr_reader :name
+      attr_accessor :rust_struct
+
+      def initialize(name)
+        @name = name
+      end
+
+      def children
+        @children ||= {}
+      end
+    end
+
+    class RubyModuleTree
+      class << self
+        def from_structs(rust_structs)
+          root = RubyModule.new(nil)
+
+          rust_structs.each do |rust_struct|
+            current = root
+
+            rust_struct.ruby_class_name.split("::").each do |ns|
+              if !current.children.include?(ns)
+                current.children[ns] = RubyModule.new(ns)
+              end
+
+              current = current.children[ns]
+            end
+
+            current.rust_struct = rust_struct
+          end
+
+          new(root)
+        end
+      end
+
+      include Utils
+
+      attr_reader :root
+
+      def initialize(root)
+        @root = root
+      end
+
+      def to_ruby_classes(indent: "")
+        to_ruby_classes_helper(root.children["Yass"], ["Yass"], indent)
+      end
+
+      def to_visitor_methods(indent:)
+        to_visitor_methods_helper(root.children["Yass"], ["Yass"], indent)
+      end
+
+      def merge(other)
+        if root.name != other.root.name
+          raise ArgumentError, "this tree and other tree have different names, '#{name}' vs '#{other.root.name}'"
+        end
+
+        new_root = merge_helper(root, other.root)
+        self.class.new(new_root)
+      end
+
+      private
+
+      def merge_helper(first, second)
+        RubyModule.new(first.name).tap do |mod|
+          first.children.each do |key, first_child_mod|
+            if (second_child_mod = second.children[key])
+              mod.children[key] = merge_helper(first_child_mod, second_child_mod)
+            else
+              mod.children[key] = first_child_mod
+            end
+          end
+
+          second.children.each do |key, second_child_mod|
+            # merge for identical keys should happen in first pass above
+            if !first.children.include?(key)
+              mod.children[key] = second_child_mod
+            end
+          end
+        end
+      end
+
+      def to_ruby_classes_helper(mod, nesting, indent = "")
+        class_or_module = Kernel.const_get(nesting.join("::"))
+        class_or_module_def = class_or_module.class == Class ? "class #{mod.name}" : "module #{mod.name}"
+
+        children = mod.children.map do |mod_name, child|
+          to_ruby_classes_helper(child, [*nesting, mod_name], indent + "  ")
+        end
+
+        accept_method = if mod.rust_struct
+          [
+            "#{indent}  def accept(visitor)",
+            "#{indent}    visitor.visit_#{nesting_to_s(nesting[1..-1])}(self)",
+            "#{indent}  end",
+          ]
+        end
+
+        kind_method = if mod.rust_struct
+          [
+            "#{indent}  def kind",
+            "#{indent}    :#{underscore(nesting.last).downcase}",
+            "#{indent}  end",
+          ]
+        end
+
+        constants = if mod.rust_struct
+          method_names = class_or_module.instance_methods - Object.methods - [:accept, :to_h]
+
+          if method_names.size > 0
+            [
+              "#{indent}  RUBY_METHODS = %i(#{method_names.map(&:to_s).sort.join(" ")}).freeze"
+            ]
+          end
+        end
+
+        includes = if mod.rust_struct
+          ["#{indent}  include ::Yass::Node"]
+        end
+
+        lines = [
+          "#{indent}#{class_or_module_def}",
+          *join_line_groups(
+            constants,
+            includes,
+            accept_method,
+            kind_method,
+            (children.empty? ? [] : [children.join("\n\n")]),
+          ),
+          "#{indent}end",
+        ]
+
+        lines.join("\n")
+      end
+
+      def to_visitor_methods_helper(mod, nesting, indent)
+        line_groups = []
+
+        if mod.rust_struct
+          method_name = "visit_#{nesting_to_s(nesting[1..-1])}"
+
+          line_groups << [
+            "#{indent}def #{method_name}(node)",
+            *(debug? ? ["#{indent}  puts \"Visiting #{method_name}\""] : []),
+            *mod.rust_struct.rust_methods.map do |rust_method|
+              if rust_method.visit_kind == :single
+                [
+                  "#{indent}  visit(node.#{rust_method.name})"
+                ]
+              else
+                [
+                  "#{indent}  visit_list(node.#{rust_method.name})"
+                ]
+              end
+            end,
+            "#{indent}end",
+          ]
+        end
+
+        mod.children.each do |mod_name, child|
+          line_groups << to_visitor_methods_helper(child, [*nesting, mod_name], indent)
+        end
+
+        join_line_groups(*line_groups)
+      end
+
+      def debug?
+        !!ENV["DEBUG"]
+      end
+    end
+  end
+end

data/codegen/rust_file_set.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "ruby_module_tree"
+
+module Yass
+  module Codegen
+    class RustStruct
+      attr_reader :name, :ruby_class_name, :rust_methods
+
+      def initialize(name:, ruby_class_name:, rust_methods:)
+        @name = name
+        @ruby_class_name = ruby_class_name
+        @rust_methods = rust_methods
+      end
+    end
+
+    class RustMethod
+      attr_reader :name, :return_type, :visit_kind
+
+      def initialize(name:, return_type:, visit_kind:)
+        @name = name
+        @return_type = return_type
+        @visit_kind = visit_kind
+      end
+    end
+
+    class RustFileSet
+      attr_reader :rust_file_paths
+
+      def initialize(rust_file_paths)
+        @rust_file_paths = rust_file_paths
+      end
+
+      def structs
+        @structs ||= rust_file_paths.flat_map do |rust_file|
+          rust_code = File.read(rust_file)
+
+          rust_code.scan(/#\[magnus(?:\:\:wrap)?\(class = "([\w:]+)"(?:, mark)?\)\]\s+pub struct (\w+)/).map do |ruby_class_name, rust_struct_name|
+            next unless ruby_class_name && rust_struct_name
+
+            m = rust_code.match(/impl\s+#{rust_struct_name}\s+(\{)/)
+            next unless m
+
+            start = pos = m.end(1)
+            count = 1
+
+            while count > 0
+              case rust_code[pos]
+              when "{"
+                count += 1
+              when "}"
+                count -= 1
+              end
+
+              pos += 1
+            end
+
+            impl_body = rust_code[start..pos]
+            rust_method_names = impl_body.scan(/pub fn (\w+)\(ruby: &Ruby, rb_self: typed_data::Obj<Self>\) -> ([\w<>:, ]+) \{/)
+            rust_methods = []
+
+            rust_method_names.each do |name, return_type|
+              if ["Option<Value>", "Value"].include?(return_type)
+                rust_methods << RustMethod.new(name: name, return_type: return_type, visit_kind: :single)
+              elsif ["RArray", "Result<RArray, Error>"].include?(return_type)
+                rust_methods << RustMethod.new(name: name, return_type: return_type, visit_kind: :multiple)
+              end
+            end
+
+            RustStruct.new(
+              name: rust_struct_name,
+              ruby_class_name: ruby_class_name,
+              rust_methods: rust_methods
+            )
+          end
+        end
+      end
+
+      def module_tree
+        @module_tree ||= RubyModuleTree.from_structs(structs)
+      end
+    end
+  end
+end

data/codegen/utils.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Yass
+  module Codegen
+    module Utils
+      def underscore(str)
+        str.gsub(/(?<=[A-Z])(?=[A-Z][a-z])|(?<=[a-z\d])(?=[A-Z])/, "_")
+      end
+
+      def nesting_to_s(nesting)
+        nesting
+          .map { |part| underscore(part).downcase }
+          .map { |part| part == "declarations" ? "declaration" : part }
+          .join("_")
+      end
+
+      def join_line_groups(*line_groups)
+        result = line_groups.compact.reject(&:empty?).flat_map do |group|
+          [*group.flatten, ""]
+        end
+
+        result.pop
+        result
+      end
+    end
+  end
+end

data/dockerfiles/windows.dockerfile

@@ -1,3 +1,3 @@
-FROM rbsys/x64-mingw-ucrt:0.9.124
+FROM rbsys/x64-mingw-ucrt:0.9.126
 
 RUN apt-get update && apt-get install -y python3

data/examples/basic_example.rb

@@ -0,0 +1,32 @@
+require "yass"
+require "pp"
+
+sheet = Yass::Parser.parse(<<~CSS)
+  h1 {
+    align-items: center;
+    display: flex;
+    position: absolute;
+  }
+CSS
+
+# this is the whole h1 { ... } rule
+first_rule = sheet.rules.first
+puts first_rule.class  # => Yass::StyleRule
+
+# this is the h1 selector
+first_selector = first_rule.selectors.first.children.first
+puts first_selector.value  # => "h1"
+
+# this is all the declarations inside the h1 rule
+declarations = first_rule.declarations
+
+# this is the first align-items declaration
+declaration = declarations.first
+puts declaration.kind   # => :align_items
+puts declaration.class  # => Yass::Declarations::AlignItems
+puts declaration.value  # => :center
+
+# this will turn the entire stylesheet into a JSON-compatible
+# data structure (only arrays, hashes, strings, etc) and
+# pretty-print it
+pp sheet.to_h

data/examples/font_example.rb

@@ -0,0 +1,19 @@
+require "yass"
+
+sheet = Yass::Parser.parse(<<~CSS)
+  @font-face {
+    font-family: "Bitstream Vera Serif Bold";
+    src: url("https://mdn.github.io/shared-assets/fonts/FiraSans-Regular.woff2");
+  }
+CSS
+
+# this is the whole @font-face { ... } rule
+first_rule = sheet.rules.first
+puts first_rule.class  # => Yass::FontFaceRule
+
+family = first_rule.family
+puts family.name  # => "Bitstream Vera Serif Bold"
+
+first_source = first_rule.sources.first
+puts first_source.class          # => Yass::Font::Source::Url
+puts first_source.specified_url  # => "https://mdn.github.io/shared-assets/fonts/FiraSans-Regular.woff2"

data/examples/media_example.rb

@@ -0,0 +1,31 @@
+require "yass"
+
+sheet = Yass::Parser.parse(<<~CSS)
+  @media screen and (max-width: 600px) {
+    .container {
+      flex-direction: column;
+    }
+  }
+CSS
+
+# this is the whole @media { ... } rule
+first_rule = sheet.rules.first
+puts first_rule.class  # => Yass::MediaRule
+
+# this is the "screen and ..." part
+first_query = first_rule.media_queries.first
+puts first_query.media_type.value       # => "screen"
+puts first_query.query_condition.value  # => "(max-width: 600px)"
+
+# Sadly Stylo doesn't give us access to the full parse tree for the
+# query condition, so the best we can do is emit the unparsed string.
+
+# this is the .container rule
+first_nested_rule = first_rule.rules.first
+first_selector = first_nested_rule.selectors.first.children.first
+puts first_selector.value  # => "container"
+
+# this is the flex-direction declaration
+first_declaration = first_nested_rule.declarations.first
+puts first_declaration.kind   # => :flex_direction
+puts first_declaration.value  # => :column

data/examples/visitor_example.rb

@@ -0,0 +1,41 @@
+require "yass"
+
+sheet = Yass::Parser.parse(<<~CSS)
+  h1 {
+    align-items: center;
+    display: flex;
+    position: absolute;
+  }
+
+  .left {
+    float: left;
+  }
+
+  .right {
+    float: right;
+  }
+
+  #thing {
+    visibility: hidden;
+  }
+CSS
+
+class MyVisitor < Yass::Visitor
+  def visit_selector_local_name(node)
+    # prints "h1"
+    puts node.value
+  end
+
+  def visit_selector_klass(node)
+    # prints "left" and "right"
+    puts node.value
+  end
+
+  def visit_selector_id(node)
+    # prints "thing"
+    puts node.value
+  end
+end
+
+visitor = MyVisitor.new
+visitor.visit(sheet)