sass-embedded 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e03d2c1775fdd10b7f9d2b21898ac0a6e31e0be96157139742384c7be9b4275a
-  data.tar.gz: dacdc9589a8da93246b791794f97be2c8818f8a492d77e473c9fa543fd49db9e
+  metadata.gz: d8c00ba9bcce40d392862171f66b9ff3ef2ce1ef13e0a9d30a8541bc93804f6e
+  data.tar.gz: 9d4ccb5ab536b1f6a76a0e350a1244e00059d42db1ce666e5f7b19a84343424c
 SHA512:
-  metadata.gz: 3be32cd37a7078fceabd16c661cf985fdfc1aa31fbf8b88e6c768cb8edd57749a30e28a77f367d6cc8c6c505710f402e1970ae6c12210b3f46fc10a42cf8d81d
-  data.tar.gz: 5a122cd7c2e883f28b9401ce70d8fb43fcfcf39e1ff64484f5bf036c6978ca1a01cf8d69b1ebbf22f0fde81f98272127cf5a96d381b0279028d316d90775ebfb
+  metadata.gz: 7c6e542f29de342a3e9358136d3dda10be13d74c44c1a0e86be21f22a96997835a192aaf041d4a16d4092317de272d8be5589ad9075504057c9dbd7992be8b39
+  data.tar.gz: c05f1f8cd413387803ee9078fbb6670f21fc24ddde8b2661f64b495b7418ebea1488b496d98bcad9ebedd6e4f04532441652bf3b8aa2f4587a3780df548c0318

data/.rubocop.yml

@@ -7,8 +7,5 @@ AllCops:
 
   NewCops: enable
 
-Layout/LineLength:
-  Enabled: false
-
 Metrics:
   Enabled: false

data/README.md

@@ -6,6 +6,12 @@ This is a Ruby library that implements the host side of the [Embedded Sass proto
 
 It exposes a Ruby API for Sass that's backed by a native [Dart Sass](https://sass-lang.com/dart-sass) executable.
 
+## Install
+
+``` sh
+gem install sass-embedded
+```
+
 ## Usage
 
 ``` ruby
@@ -14,6 +20,26 @@ require "sass"
 Sass.render(file: "style.scss")
 ```
 
+## Options
+
+`Sass.render()` support the following options:
+
+- [`data`](https://sass-lang.com/documentation/js-api#data)
+- [`file`](https://sass-lang.com/documentation/js-api#file)
+- [`indented_syntax`](https://sass-lang.com/documentation/js-api#indentedsyntax)
+- [`include_paths`](https://sass-lang.com/documentation/js-api#includepaths)
+- [`output_style`](https://sass-lang.com/documentation/js-api#outputstyle)
+- [`indent_type`](https://sass-lang.com/documentation/js-api#indenttype)
+- [`indent_width`](https://sass-lang.com/documentation/js-api#indentwidth)
+- [`linefeed`](https://sass-lang.com/documentation/js-api#linefeed)
+- [`source_map`](https://sass-lang.com/documentation/js-api#sourcemap)
+- [`out_file`](https://sass-lang.com/documentation/js-api#outfile)
+- [`omit_source_map_url`](https://sass-lang.com/documentation/js-api#omitsourcemapurl)
+- [`source_map_embed`](https://sass-lang.com/documentation/js-api#sourcemapembed)
+- [`source_map_root`](https://sass-lang.com/documentation/js-api#sourcemaproot)
+- [`functions`](https://sass-lang.com/documentation/js-api#functions)
+- [`importer`](https://sass-lang.com/documentation/js-api#importer)
+
 ---
 
 Disclaimer: this is not an official Google product.

data/ext/extconf.rb

@@ -8,12 +8,24 @@ require 'fileutils'
 require_relative '../lib/sass/platform'
 
 module Sass
-  # Install dependencies for sass-embedded during gem install
+  # The dependency downloader. This downloads all the dependencies during gem
+  # installation. The companion Makefile then unpacks all downloaded
+  # dependencies. By default it downloads the latest release of each
+  # dependency from GitHub releases.
+  #
+  # It is possible to specify an alternative source or version of each
+  # dependency. Local sources can be used for offline installation.
+  #
+  # @example
+  #   gem install sass-embedded -- \
+  #     --with-protoc=file:///path/to/protoc-*.zip \
+  #     --with-sass-embedded=file:///path/to/sass_embedded-*.(tar.gz|zip) \
+  #     --with-sass-embedded-protocol=file:///path/to/embedded_sass.proto
   class Extconf
     def initialize
+      get_with_config('protoc', true) { latest_protoc }
       get_with_config('sass-embedded', true) { latest_sass_embedded }
       get_with_config('sass-embedded-protocol', true) { latest_sass_embedded_protocol }
-      get_with_config('protoc', true) { latest_protoc }
     end
 
     private

data/lib/sass.rb

@@ -1,50 +1,72 @@
 # frozen_string_literal: true
 
-# The Sass module
+# The Sass module. This communicates with Embedded Dart Sass using
+# the Embedded Sass protocol.
 module Sass
-  # The global include_paths for Sass files. This is meant for plugins and
-  # libraries to register the paths to their Sass stylesheets to that they may
-  # be `@imported`. This include path is used by every instance of
-  # {Sass::Embedded}. They are lower-precedence than any include paths passed
-  # in via the `:include_paths` option.
-  #
-  # If the `SASS_PATH` environment variable is set,
-  # the initial value of `include_paths` will be initialized based on that.
-  # The variable should be a colon-separated list of path names
-  # (semicolon-separated on Windows).
-  #
-  # @example
-  #   Sass.include_paths << File.dirname(__FILE__) + '/sass'
-  # @return [Array<String, Pathname>]
-  def self.include_paths
-    @include_paths ||= if ENV['SASS_PATH']
-                         ENV['SASS_PATH'].split(File::PATH_SEPARATOR)
-                       else
-                         []
-                       end
-  end
+  class << self
+    # The global {.include_paths} for Sass files. This is meant for plugins and
+    # libraries to register the paths to their Sass stylesheets to that they may
+    # be included via `@import` or `@use`. This include path is used by every
+    # instance of {Sass::Embedded}. They are lower-precedence than any include
+    # paths passed in via the `include_paths` option.
+    #
+    # If the `SASS_PATH` environment variable is set,
+    # the initial value of `include_paths` will be initialized based on that.
+    # The variable should be a colon-separated list of path names
+    # (semicolon-separated on Windows).
+    #
+    # @example
+    #   Sass.include_paths << File.dirname(__FILE__) + '/sass'
+    # @return [Array]
+    def include_paths
+      @include_paths ||= if ENV['SASS_PATH']
+                           ENV['SASS_PATH'].split(File::PATH_SEPARATOR)
+                         else
+                           []
+                         end
+    end
+
+    # The global {.info} method. This instantiates a global {Embedded} instance
+    # and calls {Embedded#info}.
+    #
+    # @raise [ProtocolError]
+    def info
+      embedded.info
+    end
+
+    # The global {.render} method. This instantiates a global {Embedded} instance
+    # and calls {Embedded#render}.
+    #
+    # See {file:README.md#options} for supported options.
+    #
+    # @example
+    #   Sass.render(data: 'h1 { font-size: 40px; }')
+    # @example
+    #   Sass.render(file: 'style.css')
+    # @return [Result]
+    # @raise [ProtocolError]
+    # @raise [RenderError]
+    def render(**kwargs)
+      embedded.render(**kwargs)
+    end
+
+    private
+
+    def embedded
+      return @embedded if defined?(@embedded) && !@embedded.closed?
 
-  # The global render methods. This method automatically instantiates a
-  # global {Sass::Embedded} instance when invoked the first time and call
-  # `:render` method on the instance thereafter. The global {Sass::Embedded}
-  # is automatically closed via {Kernel.at_exit}.
-  # @example
-  #   Sass.render(options)
-  # @return [Hash]
-  def self.render(**kwargs)
-    unless defined? @embedded
       @embedded = Sass::Embedded.new
-      at_exit do
-        @embedded.close
-      end
     end
-    @embedded.render(**kwargs)
   end
 end
 
-require_relative 'sass/version'
-require_relative 'sass/error'
 require_relative 'sass/platform'
 require_relative 'sass/util'
+require_relative 'sass/struct'
+require_relative 'sass/result'
+require_relative 'sass/error'
 require_relative 'sass/transport'
+require_relative 'sass/observer'
+require_relative 'sass/version'
+require_relative 'sass/render'
 require_relative 'sass/embedded'

data/lib/sass/embedded.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
+require 'base64'
+require 'json'
+
 module Sass
-  # The interface for using dart-sass-embedded
+  # The {Embedded} host for using dart-sass-embedded. Each instance creates
+  # its own {Transport}.
+  #
+  # @example
+  #   embedded = Sass::Embedded.new
+  #   result = embedded.render(data: 'h1 { font-size: 40px; }')
+  #   result = embedded.render(file: 'style.css')
+  #   embedded.close
   class Embedded
     def initialize
       @transport = Transport.new
@@ -9,308 +19,212 @@ module Sass
       @id = 0
     end
 
-    # rubocop:disable Lint/UnusedMethodArgument
+    # The {Embedded#info} method.
+    #
+    # @raise [ProtocolError]
+    def info
+      @info ||= Version.new(@transport, next_id).fetch
+    end
 
+    # The {Embedded#render} method.
+    #
+    # See {file:README.md#options} for supported options.
+    #
+    # @return [Result]
+    # @raise [ProtocolError]
+    # @raise [RenderError]
     def render(data: nil,
                file: nil,
                indented_syntax: false,
                include_paths: [],
                output_style: :expanded,
-               precision: 5,
                indent_type: :space,
                indent_width: 2,
                linefeed: :lf,
-               source_comments: false,
                source_map: false,
                out_file: nil,
                omit_source_map_url: false,
-               source_map_contents: false,
+               # source_map_contents: false,
                source_map_embed: false,
                source_map_root: '',
                functions: {},
                importer: [])
-      # rubocop:enable Lint/UnusedMethodArgument
-
       start = Util.now
 
-      compilation_id = next_id
-
-      renderer = Renderer.new(
-        data: data,
-        file: file,
-        indented_syntax: indented_syntax,
-        include_paths: include_paths,
-        output_style: output_style,
-        source_map: source_map,
-        out_file: out_file,
-        functions: functions,
-        importer: importer
-      )
-
-      response = @transport.send renderer.compile_request(compilation_id), compilation_id
-
-      loop do
-        case response
-        when EmbeddedProtocol::OutboundMessage::CompileResponse
-          break
-        when EmbeddedProtocol::OutboundMessage::CanonicalizeRequest
-          response = @transport.send renderer.canonicalize_response(response), compilation_id
-        when EmbeddedProtocol::OutboundMessage::ImportRequest
-          response = @transport.send renderer.import_response(response), compilation_id
-        when EmbeddedProtocol::OutboundMessage::FunctionCallRequest
-          response = @transport.send renderer.function_call_response(response), compilation_id
-        when EmbeddedProtocol::ProtocolError
-          raise ProtocolError, response.message
-        else
-          raise ProtocolError, "Unexpected packet received: #{response}"
-        end
-      end
-
-      if response.failure
+      indent_type = parse_indent_type(indent_type)
+      indent_width = parse_indent_width(indent_width)
+      linefeed = parse_linefeed(linefeed)
+
+      message = Render.new(@transport, next_id,
+                           data: data,
+                           file: file,
+                           indented_syntax: indented_syntax,
+                           include_paths: include_paths,
+                           output_style: output_style,
+                           source_map: source_map,
+                           out_file: out_file,
+                           functions: functions,
+                           importer: importer).fetch
+
+      if message.failure
         raise RenderError.new(
-          response.failure.message,
-          response.failure.formatted,
-          if response.failure.span
-            response.failure.span.url == '' ? 'stdin' : URI.parse(response.failure.span.url).path
+          message.failure.message,
+          message.failure.formatted,
+          if message.failure.span.nil?
+            nil
+          elsif message.failure.span.url == ''
+            'stdin'
+          else
+            Util.path(message.failure.span.url)
           end,
-          response.failure.span ? response.failure.span.start.line + 1 : nil,
-          response.failure.span ? response.failure.span.start.column + 1 : nil,
+          message.failure.span ? message.failure.span.start.line + 1 : nil,
+          message.failure.span ? message.failure.span.start.column + 1 : nil,
           1
         )
       end
 
+      map, source_map = post_process_map(map: message.success.source_map,
+                                         file: file,
+                                         out_file: out_file,
+                                         source_map: source_map,
+                                         source_map_root: source_map_root)
+
+      css = post_process_css(css: message.success.css,
+                             indent_type: indent_type,
+                             indent_width: indent_width,
+                             linefeed: linefeed,
+                             map: map,
+                             out_file: out_file,
+                             omit_source_map_url: omit_source_map_url,
+                             source_map: source_map,
+                             source_map_embed: source_map_embed)
+
       finish = Util.now
 
-      {
-        css: response.success.css,
-        map: response.success.source_map,
-        stats: {
-          entry: file.nil? ? 'data' : file,
-          start: start,
-          end: finish,
-          duration: finish - start
-        }
-      }
+      stats = Result::Stats.new(file.nil? ? 'data' : file, start, finish, finish - start)
+
+      Result.new(css, map, stats)
     end
 
     def close
       @transport.close
-      nil
     end
 
-    private
-
-    def info
-      version_response = @transport.send EmbeddedProtocol::InboundMessage::VersionRequest.new(
-        id: next_id
-      )
-      {
-        compiler_version: version_response.compiler_version,
-        protocol_version: version_response.protocol_version,
-        implementation_name: version_response.implementation_name,
-        implementation_version: version_response.implementation_version
-      }
+    def closed?
+      @transport.closed?
     end
 
-    def next_id
-      @id_semaphore.synchronize do
-        @id += 1
-        @id = 0 if @id == Transport::PROTOCOL_ERROR_ID
-        @id
-      end
-    end
-
-    # Helper class that maintains render state
-    class Renderer
-      def initialize(data:,
-                     file:,
-                     indented_syntax:,
-                     include_paths:,
-                     output_style:,
-                     source_map:,
-                     out_file:,
-                     functions:,
-                     importer:)
-        raise ArgumentError, 'Either :data or :file must be set.' if file.nil? && data.nil?
+    private
 
-        @data = data
-        @file = file
-        @indented_syntax = indented_syntax
-        @include_paths = include_paths
-        @output_style = output_style
-        @source_map = source_map
-        @out_file = out_file
-        @global_functions = functions.keys
-        @functions = functions.transform_keys do |key|
-          key.to_s.split('(')[0].chomp
-        end
-        @importer = importer
-        @import_responses = {}
-      end
+    def post_process_map(map:,
+                         file:,
+                         out_file:,
+                         source_map:,
+                         source_map_root:)
+      return if map.nil? || map.empty?
 
-      def compile_request(id)
-        EmbeddedProtocol::InboundMessage::CompileRequest.new(
-          id: id,
-          string: string,
-          path: path,
-          style: style,
-          source_map: source_map,
-          importers: importers,
-          global_functions: global_functions,
-          alert_color: $stderr.tty?,
-          alert_ascii: Platform::OS == 'windows'
-        )
-      end
-
-      def canonicalize_response(canonicalize_request)
-        url = Util.file_uri(File.absolute_path(canonicalize_request.url, (@file.nil? ? 'stdin' : @file)))
+      map_data = JSON.parse(map)
 
-        begin
-          result = @importer[canonicalize_request.importer_id].call canonicalize_request.url, @file
-          raise result if result.is_a? StandardError
-        rescue StandardError => e
-          return EmbeddedProtocol::InboundMessage::CanonicalizeResponse.new(
-            id: canonicalize_request.id,
-            error: e.message
-          )
-        end
+      map_data['sourceRoot'] = source_map_root
 
-        if result&.key? :contents
-          @import_responses[url] = EmbeddedProtocol::InboundMessage::ImportResponse.new(
-            id: canonicalize_request.id,
-            success: EmbeddedProtocol::InboundMessage::ImportResponse::ImportSuccess.new(
-              contents: result[:contents],
-              syntax: EmbeddedProtocol::Syntax::SCSS,
-              source_map_url: nil
-            )
-          )
-          EmbeddedProtocol::InboundMessage::CanonicalizeResponse.new(
-            id: canonicalize_request.id,
-            url: url
-          )
-        elsif result&.key? :file
-          canonicalized_url = Util.file_uri(result[:file])
+      source_map_path = if source_map.is_a? String
+                          source_map
+                        else
+                          "#{out_file}.map"
+                        end
 
-          # TODO: FileImportRequest is not supported yet.
-          # Workaround by reading contents and return it when server asks
-          @import_responses[canonicalized_url] = EmbeddedProtocol::InboundMessage::ImportResponse.new(
-            id: canonicalize_request.id,
-            success: EmbeddedProtocol::InboundMessage::ImportResponse::ImportSuccess.new(
-              contents: File.read(result[:file]),
-              syntax: EmbeddedProtocol::Syntax::SCSS,
-              source_map_url: nil
-            )
-          )
+      source_map_dir = File.dirname(source_map_path)
 
-          EmbeddedProtocol::InboundMessage::CanonicalizeResponse.new(
-            id: canonicalize_request.id,
-            url: canonicalized_url
-          )
-        else
-          EmbeddedProtocol::InboundMessage::CanonicalizeResponse.new(
-            id: canonicalize_request.id
-          )
-        end
+      if out_file
+        map_data['file'] = Util.relative(source_map_dir, out_file)
+      elsif file
+        ext = File.extname(file)
+        map_data['file'] = "#{file[0..(ext.empty? ? -1 : -ext.length - 1)]}.css"
+      else
+        map_data['file'] = 'stdin.css'
       end
 
-      def import_response(import_request)
-        url = import_request.url
-
-        if @import_responses.key? url
-          @import_responses[url].id = import_request.id
+      map_data['sources'].map! do |source|
+        if source.start_with? Util::FILE_PROTOCOL
+          Util.relative(source_map_dir, Util.path(source))
         else
-          @import_responses[url] = EmbeddedProtocol::InboundMessage::ImportResponse.new(
-            id: import_request.id,
-            error: "Failed to import: #{url}"
-          )
+          source
         end
-
-        @import_responses[url]
-      end
-
-      def function_call_response(function_call_request)
-        EmbeddedProtocol::InboundMessage::FunctionCallResponse.new(
-          id: function_call_request.id,
-          success: @functions[function_call_request.name].call(*function_call_request.arguments)
-        )
-      rescue StandardError => e
-        EmbeddedProtocol::InboundMessage::FunctionCallResponse.new(
-          id: function_call_request.id,
-          error: e.message
-        )
       end
 
-      private
+      [-JSON.generate(map_data), source_map_path]
+    end
 
-      def syntax
-        if @indented_syntax == true
-          EmbeddedProtocol::Syntax::INDENTED
-        else
-          EmbeddedProtocol::Syntax::SCSS
+    def post_process_css(css:,
+                         indent_type:,
+                         indent_width:,
+                         linefeed:,
+                         map:,
+                         omit_source_map_url:,
+                         out_file:,
+                         source_map:,
+                         source_map_embed:)
+      css = +css
+      if indent_width != 2 || indent_type.to_sym != :space
+        indent = indent_type * indent_width
+        css.gsub!(/^ +/) do |space|
+          indent * (space.length / 2)
         end
       end
-
-      def url
-        return if @file.nil?
-
-        Util.file_uri(@file)
+      css.gsub!("\n", linefeed) if linefeed != "\n"
+
+      unless map.nil? || omit_source_map_url == true
+        url = if source_map_embed
+                "data:application/json;base64,#{Base64.strict_encode64(map)}"
+              elsif out_file
+                Util.relative(File.dirname(out_file), source_map)
+              else
+                source_map
+              end
+        css += "#{linefeed}/*# sourceMappingURL=#{url} */"
       end
 
-      def string
-        return if @data.nil?
+      -css
+    end
 
-        EmbeddedProtocol::InboundMessage::CompileRequest::StringInput.new(
-          source: @data,
-          url: url,
-          syntax: syntax
-        )
+    def parse_indent_type(indent_type)
+      case indent_type.to_sym
+      when :space
+        ' '
+      when :tab
+        "\t"
+      else
+        raise ArgumentError, 'indent_type must be one of :space, :tab'
       end
+    end
 
-      def path
-        @file if @data.nil?
-      end
+    def parse_indent_width(indent_width)
+      raise ArgumentError, 'indent_width must be an integer' unless indent_width.is_a? Integer
+      raise RangeError, 'indent_width must be in between 0 and 10 (inclusive)' unless indent_width.between? 0, 10
 
-      def style
-        case @output_style.to_sym
-        when :expanded
-          EmbeddedProtocol::OutputStyle::EXPANDED
-        when :compressed
-          EmbeddedProtocol::OutputStyle::COMPRESSED
-        when :nested, :compact
-          raise ArgumentError, "#{@output_style} is not a supported output_style"
-        else
-          raise ArgumentError, "#{@output_style} is not a valid utput_style"
-        end
-      end
+      indent_width
+    end
 
-      def source_map
-        @source_map.is_a?(String) || (@source_map == true && !@out_file.nil?)
+    def parse_linefeed(linefeed)
+      case linefeed.to_sym
+      when :lf
+        "\n"
+      when :lfcr
+        "\n\r"
+      when :cr
+        "\r"
+      when :crlf
+        "\r\n"
+      else
+        raise ArgumentError, 'linefeed must be one of :lf, :lfcr, :cr, :crlf'
       end
+    end
 
-      attr_reader :global_functions
-
-      # Order
-      # 1. Loading a file relative to the file in which the @use or @import appeared.
-      # 2. Each custom importer.
-      # 3. Loading a file relative to the current working directory.
-      # 4. Each load path in includePaths
-      # 5. Each load path specified in the SASS_PATH environment variable, which should be semicolon-separated on Windows and colon-separated elsewhere.
-      def importers
-        custom_importers = @importer.map.with_index do |_, id|
-          EmbeddedProtocol::InboundMessage::CompileRequest::Importer.new(
-            importer_id: id
-          )
-        end
-
-        include_path_importers = @include_paths
-                                 .concat(Sass.include_paths)
-                                 .map do |include_path|
-          EmbeddedProtocol::InboundMessage::CompileRequest::Importer.new(
-            path: File.absolute_path(include_path)
-          )
-        end
-
-        custom_importers.concat include_path_importers
+    def next_id
+      @id_semaphore.synchronize do
+        @id += 1
+        @id = 0 if @id == Transport::PROTOCOL_ERROR_ID
+        @id
       end
     end
   end