sass-embedded 1.0.6 → 1.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb22fd222502bd171a92c0f112b0644dda7b3c6badf12c9f9aa9b079c0856681
-  data.tar.gz: fd6f3666396b577de10d2c8403dd3bbdcf382b9d7e6a656d2da7ca6750ff0e38
+  metadata.gz: e66ada7e45e9d2645c9c11569f907001a4d8f9711df90f9cebe726e0a40d9539
+  data.tar.gz: aa2139021df463e31a2fa6f02d9515dd6b9553b57d73d38e831ad67ecb688275
 SHA512:
-  metadata.gz: e75993c794dfde2f004cff309537562914b6cf5efcc9898f5b5b5b2e92c8cf5f616397ba363477768c36c2e42a1548c3f6897d2d28cdd4c4010489b744ff0626
-  data.tar.gz: 1116525243f799d4fa7ac0fb52fe3f59f5a5d2c08256d347c88ff19a48eef714ce3e2ccc58e8b71b61ebb055b80322b84017df207b5b047a802b8dea585fd73c
+  metadata.gz: bc77ad8ef5cbd139360443308899212ce95fd4b3be3be31fbca1f331f7cc73e6bd5ad0f6f2bc853d486ca0a90bc1e3fdf043adbcb534060f17c2209a7eac9499
+  data.tar.gz: 61918d88ebfa21159851b0294d1366b2ff403c3168592dc70554c68810a777552ecb773849e790fd9f8bd1be1f2e4839732700b02a5faf7b4db448776c34b120

data/README.md

@@ -15,11 +15,24 @@ gem install sass-embedded
 
 ## Usage
 
+The Ruby API provides two entrypoints for compiling Sass to CSS.
+
+- `Sass.compile` takes a path to a Sass file and return the result of compiling that file to CSS.
+
+``` ruby
+require 'sass'
+
+result = Sass.compile('style.scss')
+puts result.css
+```
+
+- `Sass.compile_string` takes a string that represents the contents of a Sass file and return the result of compiling that file to CSS.
+
 ``` ruby
 require 'sass'
 
-Sass.compile('style.scss')
-Sass.compile_string('h1 { font-size: 40px; }')
+result = Sass.compile_string('h1 { font-size: 40px; }')
+puts result.css
 ```
 
 ---

data/ext/sass/Rakefile

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open-uri'
+require 'open3'
+require 'rake/clean'
+
+task default: %i[install clean]
+
+task install: %w[sass_embedded embedded_sass_pb.rb]
+
+CLEAN.include %w[protoc *.proto *.tar.gz *.zip]
+
+CLOBBER.include %w[sass_embedded embedded_sass_pb.rb]
+
+file 'protoc' do |t|
+  archive = fetch(ENV.fetch(t.name.upcase) { Configuration.default_protoc })
+  unzip archive, t.name
+  rm archive
+end
+
+file 'sass_embedded' do |t|
+  archive = fetch(ENV.fetch(t.name.upcase) { Configuration.default_sass_embedded })
+  if Gem.win_platform?
+    unzip archive
+  else
+    sh 'tar', '-vxzf', archive
+  end
+  rm archive
+end
+
+file 'embedded_sass.proto' => %w[sass_embedded] do |t|
+  fetch(ENV.fetch('sass_embedded_protocol'.upcase) { Configuration.default_sass_embedded_protocol }, t.name)
+end
+
+rule '_pb.rb' => %w[.proto protoc] do |t|
+  sh './protoc/bin/protoc', '--ruby_out=.', t.source
+end
+
+# This is a FileUtils extension that defines several additional commands to be
+# added to the FileUtils utility functions.
+module FileUtils
+  def unzip(archive, dest = '.')
+    if Gem.win_platform?
+      sh 'powershell', '-File', 'unzip.ps1', '-Archive', archive, '-DestinationPath', dest
+    else
+      sh 'unzip', '-od', dest, archive
+    end
+  end
+
+  def fetch(uri_or_path, dest = nil)
+    begin
+      uri = URI.parse(uri_or_path)
+      path = URI::DEFAULT_PARSER.unescape(uri.path)
+      if uri.instance_of?(URI::File) || uri.instance_of?(URI::Generic)
+        path = path.delete_prefix('/') if Gem.win_platform? && !File.file?(path)
+        raise unless File.file?(path)
+      end
+    rescue StandardError
+      raise unless File.file?(uri_or_path)
+
+      uri = nil
+      path = uri_or_path
+    end
+
+    dest = File.basename(path) if dest.nil?
+
+    if uri.nil? || uri.instance_of?(URI::File) || uri.instance_of?(URI::Generic)
+      cp path, dest
+    elsif uri.respond_to?(:open)
+      Rake.rake_output_message "curl -fsSLo #{dest} -- #{uri}" if Rake::FileUtilsExt.verbose_flag
+      unless Rake::FileUtilsExt.nowrite_flag
+        uri.open do |stream|
+          File.binwrite(dest, stream.read)
+        end
+      end
+    else
+      raise
+    end
+
+    dest
+  rescue StandardError
+    raise "Failed to fetch #{uri_or_path}"
+  end
+end
+
+# The {Configuration} module.
+module Configuration
+  module Platform
+    OS = case RbConfig::CONFIG['host_os'].downcase
+         when /linux/
+           'linux'
+         when /darwin/
+           'darwin'
+         when /freebsd/
+           'freebsd'
+         when /netbsd/
+           'netbsd'
+         when /openbsd/
+           'openbsd'
+         when /dragonfly/
+           'dragonflybsd'
+         when /sunos|solaris/
+           'solaris'
+         when *Gem::WIN_PATTERNS
+           'windows'
+         else
+           RbConfig::CONFIG['host_os'].downcase
+         end
+
+    OSVERSION = RbConfig::CONFIG['host_os'].gsub(/[^\d]/, '').to_i
+
+    CPU = RbConfig::CONFIG['host_cpu']
+
+    ARCH = case CPU.downcase
+           when /amd64|x86_64|x64/
+             'x86_64'
+           when /i\d86|x86|i86pc/
+             'i386'
+           when /ppc64|powerpc64/
+             'powerpc64'
+           when /ppc|powerpc/
+             'powerpc'
+           when /sparcv9|sparc64/
+             'sparcv9'
+           when /arm64|aarch64/ # MacOS calls it "arm64", other operating systems "aarch64"
+             'aarch64'
+           when /^arm/
+             if OS == 'darwin' # Ruby before 3.0 reports "arm" instead of "arm64" as host_cpu on darwin
+               'aarch64'
+             else
+               'arm'
+             end
+           else
+             RbConfig::CONFIG['host_cpu']
+           end
+  end
+
+  private_constant :Platform
+
+  class << self
+    def default_sass_embedded
+      repo = 'sass/dart-sass-embedded'
+
+      spec = JSON.parse(File.read(File.absolute_path('package.json', __dir__)))
+
+      tag_name = spec['dependencies']['sass-embedded']
+
+      os = case Platform::OS
+           when 'darwin'
+             'macos'
+           when 'linux'
+             'linux'
+           when 'windows'
+             'windows'
+           else
+             raise release_asset_not_available_error(repo, tag_name)
+           end
+
+      arch = case Platform::ARCH
+             when 'x86_64'
+               'x64'
+             when 'i386'
+               'ia32'
+             when 'aarch64'
+               Platform::OS == 'darwin' ? 'x64' : 'arm64'
+             else
+               raise release_asset_not_available_error(repo, tag_name)
+             end
+
+      ext = case os
+            when 'windows'
+              'zip'
+            else
+              'tar.gz'
+            end
+
+      "https://github.com/#{repo}/releases/download/#{tag_name}/sass_embedded-#{tag_name}-#{os}-#{arch}.#{ext}"
+    end
+
+    def default_protoc
+      repo = 'protocolbuffers/protobuf'
+
+      version = Gem::Dependency.new('google-protobuf').to_spec.version
+
+      tag_name = "v#{version}"
+
+      os = case Platform::OS
+           when 'darwin'
+             'osx'
+           when 'linux'
+             'linux'
+           when 'windows'
+             'win'
+           else
+             raise release_asset_not_available_error(repo, tag_name)
+           end
+
+      arch = case Platform::ARCH
+             when 'aarch64'
+               Platform::OS == 'darwin' ? 'x86_64' : 'aarch_64'
+             when 'sparcv9'
+               's390'
+             when 'i386'
+               'x86_32'
+             when 'x86_64'
+               'x86_64'
+             when 'powerpc64'
+               'ppcle_64'
+             else
+               raise release_asset_not_available_error(repo, tag_name)
+             end
+
+      os_arch = case os
+                when 'win'
+                  os + arch.split('_').last
+                else
+                  "#{os}-#{arch}"
+                end
+
+      ext = 'zip'
+
+      "https://github.com/#{repo}/releases/download/#{tag_name}/protoc-#{version}-#{os_arch}.#{ext}"
+    end
+
+    def default_sass_embedded_protocol
+      stdout, stderr, status = Open3.capture3(
+        File.absolute_path("sass_embedded/dart-sass-embedded#{Gem.win_platform? ? '.bat' : ''}", __dir__), '--version'
+      )
+      raise stderr unless status.success?
+
+      tag_name = JSON.parse(stdout)['protocolVersion']
+      "https://github.com/sass/embedded-protocol/raw/#{tag_name}/embedded_sass.proto"
+    end
+
+    private
+
+    def release_asset_not_available_error(repo, tag_name)
+      NotImplementedError.new(
+        "Release asset for #{Platform::OS} #{Platform::ARCH} "\
+        "not available at https://github.com/#{repo}/releases/tag/#{tag_name}"
+      )
+    end
+  end
+end

data/ext/sass/mkrf_conf.rb

@@ -0,0 +1,2 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true

data/ext/sass/unzip.ps1

@@ -0,0 +1,13 @@
+Param(
+    [Parameter(Mandatory)]
+    [ValidateNotNullOrEmpty()]
+    [string]$Archive,
+    [Parameter(Mandatory)]
+    [ValidateNotNullOrEmpty()]
+    [string]$DestinationPath
+)
+if (Get-Command Expand-Archive -ErrorAction SilentlyContinue) {
+    Get-Item $Archive | Expand-Archive -DestinationPath $DestinationPath -Force
+} else {
+    cscript.exe unzip.vbs $Archive $DestinationPath
+}

data/lib/sass/compile_error.rb

@@ -3,18 +3,23 @@
 module Sass
   # An exception thrown because a Sass compilation failed.
   class CompileError < StandardError
-    attr_accessor :sass_stack, :span
+    # @return [String, nil]
+    attr_accessor :sass_stack
+
+    # @return [Logger::SourceSpan, nil]
+    attr_accessor :span
 
     def initialize(message, full_message, sass_stack, span)
       super(message)
-      @full_message = full_message
-      @sass_stack = sass_stack
+      @full_message = full_message == '' ? nil : full_message.dup
+      @sass_stack = sass_stack == '' ? nil : sass_stack
       @span = span
     end
 
-    def full_message(*)
+    # @return [String]
+    def full_message(*args, **kwargs)
       if @full_message.nil?
-        super
+        super(*args, **kwargs)
       else
         @full_message
       end

data/lib/sass/compile_result.rb

@@ -2,8 +2,17 @@
 
 module Sass
   # The result of compiling Sass to CSS. Returned by {Sass.compile} and {Sass.compile_string}.
+  #
+  # @see https://sass-lang.com/documentation/js-api/interfaces/CompileResult
   class CompileResult
-    attr_reader :css, :source_map, :loaded_urls
+    # @return [String]
+    attr_reader :css
+
+    # @return [String, nil]
+    attr_reader :source_map
+
+    # @return [Array<String>]
+    attr_reader :loaded_urls
 
     def initialize(css, source_map, loaded_urls)
       @css = css

data/lib/sass/embedded/host.rb

@@ -36,6 +36,8 @@ module Sass
                           quiet_deps:,
                           verbose:)
         await do
+          alert_color = $stderr.tty? if alert_color.nil?
+
           @function_registry = FunctionRegistry.new(functions, alert_color: alert_color)
           @importer_registry = ImporterRegistry.new(importers, load_paths, alert_color: alert_color)
           @logger_registry = LoggerRegistry.new(logger)

data/lib/sass/embedded/version.rb

@@ -2,6 +2,6 @@
 
 module Sass
   class Embedded
-    VERSION = '1.0.6'
+    VERSION = '1.0.9'
   end
 end

data/lib/sass/embedded.rb

@@ -14,10 +14,31 @@ module Sass
       @channel = Channel.new
     end
 
-    # The {Embedded#compile} method.
-    #
+    # Compiles the Sass file at +path+ to CSS.
+    # @param path [String]
+    # @param load_paths [Array<String>] Paths in which to look for stylesheets loaded by rules like
+    #   {@use}[https://sass-lang.com/documentation/at-rules/use] and {@import}[https://sass-lang.com/documentation/at-rules/import].
+    # @param source_map [Boolean] Whether or not Sass should generate a source map.
+    # @param source_map_include_sources [Boolean] Whether Sass should include the sources in the generated source map.
+    # @param style [String, Symbol] The OutputStyle of the compiled CSS.
+    # @param functions [Hash<String, Proc>] Additional built-in Sass functions that are available in all stylesheets.
+    # @param importers [Array<Object>] Custom importers that control how Sass resolves loads from rules like
+    #   {@use}[https://sass-lang.com/documentation/at-rules/use] and {@import}[https://sass-lang.com/documentation/at-rules/import].
+    # @param alert_ascii [Boolean] If this is +true+, the compiler will exclusively use ASCII characters in its error
+    #   and warning messages. Otherwise, it may use non-ASCII Unicode characters as well.
+    # @param alert_color [Boolean] If this is +true+, the compiler will use ANSI color escape codes in its error and
+    #   warning messages. If it's +false+, it won't use these. If it's +nil+, the compiler will determine whether or
+    #   not to use colors depending on whether the user is using an interactive terminal.
+    # @param logger [Object] An object to use to handle warnings and/or debug messages from Sass.
+    # @param quiet_deps [Boolean] If this option is set to +true+, Sass won’t print warnings that are caused by
+    #   dependencies. A “dependency” is defined as any file that’s loaded through +load_paths+ or +importer+.
+    #   Stylesheets that are imported relative to the entrypoint are not considered dependencies.
+    # @param verbose [Boolean] By default, Dart Sass will print only five instances of the same deprecation warning per
+    #   compilation to avoid deluging users in console noise. If you set verbose to +true+, it will instead print every
+    #   deprecation warning it encounters.
     # @return [CompileResult]
     # @raise [CompileError]
+    # @see https://sass-lang.com/documentation/js-api/modules#compile
     def compile(path,
                 load_paths: [],
 
@@ -29,7 +50,7 @@ module Sass
                 importers: [],
 
                 alert_ascii: false,
-                alert_color: $stderr.tty?,
+                alert_color: nil,
                 logger: nil,
                 quiet_deps: false,
                 verbose: false)
@@ -58,10 +79,35 @@ module Sass
       )
     end
 
-    # The {Embedded#compile_string} method.
-    #
+    # Compiles a stylesheet whose contents is +source+ to CSS.
+    # @param source [String]
+    # @param importer [Object] The importer to use to handle loads that are relative to the entrypoint stylesheet.
+    # @param load_paths [Array<String>] Paths in which to look for stylesheets loaded by rules like
+    #   {@use}[https://sass-lang.com/documentation/at-rules/use] and {@import}[https://sass-lang.com/documentation/at-rules/import].
+    # @param syntax [String, Symbol] The Syntax to use to parse the entrypoint stylesheet.
+    # @param url [String] The canonical URL of the entrypoint stylesheet. If this is passed along with +importer+, it's
+    #   used to resolve relative loads in the entrypoint stylesheet.
+    # @param source_map [Boolean] Whether or not Sass should generate a source map.
+    # @param source_map_include_sources [Boolean] Whether Sass should include the sources in the generated source map.
+    # @param style [String, Symbol] The OutputStyle of the compiled CSS.
+    # @param functions [Hash<String, Proc>] Additional built-in Sass functions that are available in all stylesheets.
+    # @param importers [Array<Object>] Custom importers that control how Sass resolves loads from rules like
+    #   {@use}[https://sass-lang.com/documentation/at-rules/use] and {@import}[https://sass-lang.com/documentation/at-rules/import].
+    # @param alert_ascii [Boolean] If this is +true+, the compiler will exclusively use ASCII characters in its error
+    #   and warning messages. Otherwise, it may use non-ASCII Unicode characters as well.
+    # @param alert_color [Boolean] If this is +true+, the compiler will use ANSI color escape codes in its error and
+    #   warning messages. If it's +false+, it won't use these. If it's +nil+, the compiler will determine whether or
+    #   not to use colors depending on whether the user is using an interactive terminal.
+    # @param logger [Object] An object to use to handle warnings and/or debug messages from Sass.
+    # @param quiet_deps [Boolean] If this option is set to +true+, Sass won’t print warnings that are caused by
+    #   dependencies. A “dependency” is defined as any file that’s loaded through +load_paths+ or +importer+.
+    #   Stylesheets that are imported relative to the entrypoint are not considered dependencies.
+    # @param verbose [Boolean] By default, Dart Sass will print only five instances of the same deprecation warning per
+    #   compilation to avoid deluging users in console noise. If you set verbose to +true+, it will instead print every
+    #   deprecation warning it encounters.
     # @return [CompileResult]
     # @raise [CompileError]
+    # @see https://sass-lang.com/documentation/js-api/modules#compileString
     def compile_string(source,
                        importer: nil,
                        load_paths: [],
@@ -76,7 +122,7 @@ module Sass
                        importers: [],
 
                        alert_ascii: false,
-                       alert_color: $stderr.tty?,
+                       alert_color: nil,
                        logger: nil,
                        quiet_deps: false,
                        verbose: false)
@@ -104,7 +150,8 @@ module Sass
       )
     end
 
-    # The {Embedded#info} method.
+    # @return [String] Information about the Sass implementation.
+    # @see https://sass-lang.com/documentation/js-api/modules#info
     def info
       @info ||= "sass-embedded\t#{Host.new(@channel).version_request.implementation_version}"
     end

data/lib/sass/logger/source_location.rb

@@ -5,7 +5,10 @@ module Sass
     # A specific location within a source file.
     #
     # This is always associated with a {SourceSpan} which indicates which file it refers to.
+    #
+    # @see https://sass-lang.com/documentation/js-api/interfaces/SourceLocation
     class SourceLocation
+      # @return [Integer]
       attr_reader :offset, :line, :column
 
       def initialize(offset, line, column)

data/lib/sass/logger/source_span.rb

@@ -3,8 +3,17 @@
 module Sass
   module Logger
     # A span of text within a source file.
+    #
+    # @see https://sass-lang.com/documentation/js-api/interfaces/SourceSpan
     class SourceSpan
-      attr_reader :start, :end, :text, :url, :context
+      # @return [SourceLocation]
+      attr_reader :start, :end
+
+      # @return [String]
+      attr_reader :text
+
+      # @return [String, nil]
+      attr_reader :url, :context
 
       def initialize(start, end_, text, url, context)
         @start = start

data/lib/sass/logger.rb

@@ -2,6 +2,8 @@
 
 module Sass
   # A namespace for built-in Loggers.
+  #
+  # @see https://sass-lang.com/documentation/js-api/modules/Logger
   module Logger
     module_function
 

data/lib/sass/value/argument_list.rb

@@ -6,7 +6,12 @@ module Sass
     #
     # An argument list comes from a rest argument. It's distinct from a normal {List} in that it may contain a keyword
     # map as well as the positional arguments.
+    #
+    # @see https://sass-lang.com/documentation/js-api/classes/SassArgumentList
     class ArgumentList < Value::List
+      # @param contents [Array<Value>]
+      # @param keywords [Hash<::String, Value>]
+      # @param separator [::String]
       def initialize(contents = [], keywords = {}, separator = ',')
         super(contents, separator: separator)
 
@@ -15,6 +20,7 @@ module Sass
         @keywords = keywords.transform_keys(&:to_s).freeze
       end
 
+      # @return [Hash<::String, Value>]
       def keywords
         @keywords_accessed = true
         @keywords

data/lib/sass/value/boolean.rb

@@ -3,31 +3,39 @@
 module Sass
   module Value
     # Sass's boolean type.
+    #
+    # @see https://sass-lang.com/documentation/js-api/classes/SassBoolean
     class Boolean
       include Value
 
+      # @param value [::Boolean]
       def initialize(value)
         @value = value
       end
 
+      # @return [::Boolean]
       attr_reader :value
 
-      alias to_bool value
-
-      def assert_boolean(_name = nil)
-        self
+      # @return [Boolean]
+      def !
+        value ? Boolean::FALSE : Boolean::TRUE
       end
 
+      # @return [::Boolean]
       def ==(other)
         other.is_a?(Sass::Value::Boolean) && other.value == value
       end
 
+      # @return [Integer]
       def hash
         @hash ||= value.hash
       end
 
-      def !
-        value ? Boolean::FALSE : Boolean::TRUE
+      alias to_bool value
+
+      # @return [Boolean]
+      def assert_boolean(_name = nil)
+        self
       end
 
       # Sass's true value.