sass-embedded 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1086f5483670120b40e9741187e5150a5af9e9ad5d38159d6d57459edec350b
-  data.tar.gz: d6afead31f102a04ad4d11c82e1381b597c285ae0206564640763173e2b67fc6
+  metadata.gz: d8c00ba9bcce40d392862171f66b9ff3ef2ce1ef13e0a9d30a8541bc93804f6e
+  data.tar.gz: 9d4ccb5ab536b1f6a76a0e350a1244e00059d42db1ce666e5f7b19a84343424c
 SHA512:
-  metadata.gz: c8c534da41310d6b7e6228624d26a6e3dd94bccc4b67b2e9a25bff82251cb3b4a5d312c58ec1e498f944731cc99f4fdcb66b117278640cee2fc3d81f95924f66
-  data.tar.gz: 6d8808fc65dbb7fc4b43976beb6c8573635d874e9d72a7949f20eda5406e582ea0933a99f844256ec284e3ecf1e8e6f02b967f50854fde661470bf6834550abb
+  metadata.gz: 7c6e542f29de342a3e9358136d3dda10be13d74c44c1a0e86be21f22a96997835a192aaf041d4a16d4092317de272d8be5589ad9075504057c9dbd7992be8b39
+  data.tar.gz: c05f1f8cd413387803ee9078fbb6670f21fc24ddde8b2661f64b495b7418ebea1488b496d98bcad9ebedd6e4f04532441652bf3b8aa2f4587a3780df548c0318

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,9 +8,9 @@ require 'fileutils'
 require_relative '../lib/sass/platform'
 
 module Sass
-  # The dependency downloader. This will download all the dependencies
-  # during gem installation, and the Makefile will unpack all downloaded
-  # dependencies. By default it will download the latest release of each
+  # 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
@@ -18,9 +18,9 @@ module Sass
   #
   # @example
   #   gem install sass-embedded -- \
-  #     --with-protoc=file:///path/to/protoc-*.zip
+  #     --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 \
+  #     --with-sass-embedded-protocol=file:///path/to/embedded_sass.proto
   class Extconf
     def initialize
       get_with_config('protoc', true) { latest_protoc }

data/lib/sass.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-# The Sass module. This module will communicate with Embedded Dart Sass using
+# The Sass module. This communicates with Embedded Dart Sass using
 # the Embedded Sass protocol.
 module Sass
   class << self
-    # The global include_paths for Sass files. This is meant for plugins and
+    # 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.
+    # 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.
@@ -17,7 +17,7 @@ module Sass
     #
     # @example
     #   Sass.include_paths << File.dirname(__FILE__) + '/sass'
-    # @return [Array<String, Pathname>]
+    # @return [Array]
     def include_paths
       @include_paths ||= if ENV['SASS_PATH']
                            ENV['SASS_PATH'].split(File::PATH_SEPARATOR)
@@ -26,19 +26,26 @@ module Sass
                          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 method automatically instantiates a
-    # global {Sass::Embedded} instance when invoked the first time and call
-    # `:render` method on the instance thereafter. See {Sass::Embedded#render}
-    # for supported options.
+    # 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 [Hash]
+    # @return [Result]
+    # @raise [ProtocolError]
+    # @raise [RenderError]
     def render(**kwargs)
       embedded.render(**kwargs)
     end
@@ -53,12 +60,13 @@ module Sass
   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/info'
+require_relative 'sass/version'
 require_relative 'sass/render'
 require_relative 'sass/embedded'

data/lib/sass/embedded.rb

@@ -4,8 +4,9 @@ require 'base64'
 require 'json'
 
 module Sass
-  # The {Embedded} user interface for using dart-sass-embedded. Each instance
-  # will create its own {Transport}.
+  # 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; }')
@@ -18,20 +19,28 @@ module Sass
       @id = 0
     end
 
+    # The {Embedded#info} method.
+    #
+    # @raise [ProtocolError]
     def info
-      @info ||= Info.new(@transport, next_id).fetch
+      @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,
@@ -46,41 +55,41 @@ module Sass
       indent_width = parse_indent_width(indent_width)
       linefeed = parse_linefeed(linefeed)
 
-      result = 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 result.failure
+      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(
-          result.failure.message,
-          result.failure.formatted,
-          if result.failure.span.nil?
+          message.failure.message,
+          message.failure.formatted,
+          if message.failure.span.nil?
             nil
-          elsif result.failure.span.url == ''
+          elsif message.failure.span.url == ''
             'stdin'
           else
-            Util.path(result.failure.span.url)
+            Util.path(message.failure.span.url)
           end,
-          result.failure.span ? result.failure.span.start.line + 1 : nil,
-          result.failure.span ? result.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: result.success.source_map,
+      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: result.success.css,
+      css = post_process_css(css: message.success.css,
                              indent_type: indent_type,
                              indent_width: indent_width,
                              linefeed: linefeed,
@@ -92,16 +101,9 @@ module Sass
 
       finish = Util.now
 
-      {
-        css: css,
-        map: 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

data/lib/sass/error.rb

@@ -1,21 +1,23 @@
 # frozen_string_literal: true
 
 module Sass
-  class SassError < StandardError; end
+  class Error < StandardError; end
 
-  class ProtocolError < SassError; end
+  class ProtocolError < Error; end
 
-  # The error returned by {Embedded#render}.
-  class RenderError < SassError
-    attr_accessor :formatted, :file, :line, :column, :status
+  # The {Error} raised by {Embedded#render}.
+  class RenderError < Error
+    include Struct
+
+    attr_reader :formatted, :file, :line, :column, :status
 
     def initialize(message, formatted, file, line, column, status)
+      super(message)
       @formatted = formatted
       @file = file
       @line = line
       @column = column
       @status = status
-      super(message)
     end
 
     def backtrace

data/lib/sass/info.rb

@@ -2,7 +2,7 @@
 
 module Sass
   # The {Observer} for {Embedded#info}.
-  class Info < Observer
+  class Version < Observer
     def initialize(transport, id)
       super(transport, id)
       @transport.send EmbeddedProtocol::InboundMessage::VersionRequest.new(id: @id)

data/lib/sass/observer.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module Sass
-  # The abstract {Observer} for tracking state and observing messages
-  # from {Transport}.
+  # The {Observer} for receiving messages from {Transport}.
   class Observer
     def initialize(transport, id)
       raise NotImplementedError if instance_of? Observer

data/lib/sass/result.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Sass
+  # The {Result} of {Embedded#render}.
+  class Result
+    include Struct
+
+    attr_reader :css, :map, :stats
+
+    def initialize(css, map, stats)
+      @css = css
+      @map = map
+      @stats = stats
+    end
+
+    # The {Stats} of {Embedded#render}.
+    class Stats
+      include Struct
+
+      attr_reader :entry, :start, :end, :duration
+
+      def initialize(entry, start, finish, duration)
+        @entry = entry
+        @start = start
+        @end = finish
+        @duration = duration
+      end
+    end
+  end
+end

data/lib/sass/struct.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Sass
+  # The {Struct} module.
+  module Struct
+    def [](key)
+      instance_variable_get("@#{key}".to_sym)
+    end
+
+    def to_h
+      instance_variables.map do |variable|
+        [variable[1..].to_sym, instance_variable_get(variable)]
+      end.to_h
+    end
+
+    def to_s
+      to_h.to_s
+    end
+  end
+end

data/lib/sass/transport.rb

@@ -6,7 +6,7 @@ require_relative '../../ext/embedded_sass_pb'
 
 module Sass
   # The {Observable} {Transport} for low level communication with
-  # dart-sass-embedded using protocol buffers via stdio. Received messages
+  # `dart-sass-embedded` using protocol buffers via stdio. Received messages
   # can be observed by an {Observer}.
   class Transport
     include Observable

data/lib/sass/util.rb

@@ -3,7 +3,7 @@
 require 'pathname'
 
 module Sass
-  # The utilitiy module.
+  # The {Util} module.
   module Util
     module_function
 

data/lib/sass/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sass
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sass-embedded
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - なつき
@@ -161,6 +161,8 @@ files:
 - lib/sass/observer.rb
 - lib/sass/platform.rb
 - lib/sass/render.rb
+- lib/sass/result.rb
+- lib/sass/struct.rb
 - lib/sass/transport.rb
 - lib/sass/util.rb
 - lib/sass/version.rb