fontist 3.0.28 → 3.0.30

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdbd031efa6ca583a610246930ceddc3cc365f3b6047d49ccc9287efee8223ec
-  data.tar.gz: a5bc28594e55dc5e7a2050293338d9f19597edc44801dfe3bb5c98b9adb900ea
+  metadata.gz: d858c57f16d09454000112d1047f120b1a752a76331e3788f65cb441fe7a668c
+  data.tar.gz: 60c5f0e33198e6b7b8ad24db123280a5fff7c4eaf8b56581d3ab8c9108114b44
 SHA512:
-  metadata.gz: 2d7ec1b13570f62ebe344a5b0e11d18b13e4160ed1e76f4ccbdf93fe3f5d40d376b4af457ee5e5e3f658afbe6c9df9a144a0f011f98cbc2eb39163c15f77f014
-  data.tar.gz: 8ebaacfb87497c01fbc41c9074e4febbca0f788f7d81ab6c1d409ae0b7123cdc9d78dbd24501fb03cfa824dcc4932cb10d64f203039185582456a0a466e00410
+  metadata.gz: 581ebfd99f20a966cea6574294b4a3de879cdcea6051f916645e84ac9bd5e9ee16d4d0bfcbbd82f0291b6d6ae3e72dcf1c5524d02f6e1d67d3fbcfd880b03d73
+  data.tar.gz: 7188a89be063579e76ffd351c5ddd0c7296836a4c6162c1974ca54f79ca5cddd6134a71b3d48d04455fbc1ac8debbe1e6f2922d414a16aea2e85c83a62742fc2

data/README.adoc

@@ -311,11 +311,92 @@ Supported options:
 `-S, [--size-limit=N]`:: Specify upper limit for file size of a formula to be installed
                        (default is 300 MB)
 `-u, [--update-fontconfig]`:: Update Fontconfig
+`--collection-index=N`, `--format=FORMAT`, `--fallback-to-original`,
+`--subset-unicodes=LIST`, `--subset-text=TEXT`:: See <<Font operations>>
 
 
 NOTE: The `install` command is similar to the `Font.install` library call.
 
 
+=== Font operations
+
+Fontist can transform fonts with the https://github.com/fontist/fontisan[Fontisan]
+gem while installing, and bundle fonts into collections. Without any of these
+options, `install` copies fonts unchanged.
+
+==== Install one member of a TTC/OTC collection
+
+[source,sh]
+----
+fontist install "Noto Sans Oriya" --collection-index 1
+----
+
+Installs member 1 (zero-based) as a standalone font. An index outside the
+collection fails with `Collection index N out of range. Valid range: 0-M`.
+
+==== Convert formats
+
+[source,sh]
+----
+fontist install "Lato" --format woff2
+----
+
+Targets: `ttf`, `otf`, `woff`, `woff2`. If Fontisan cannot convert the font,
+the install fails with an error. Pass `--fallback-to-original` to install the
+original format instead.
+
+==== Subset
+
+[source,sh]
+----
+fontist install "Lato" --subset-unicodes "U+0020-007E,U+00E9"
+fontist install "Lato" --subset-text "Hello"
+----
+
+Keeps only the glyphs for those characters. Options can be combined with
+`--format`.
+
+==== Bundle a collection
+
+[source,sh]
+----
+fontist pack family.ttc Regular.ttf Bold.ttf
+----
+
+==== Ruby API
+
+[source,ruby]
+----
+Fontist::FontOperations::Extract.call("family.ttc", index: 1, output_dir: "out")
+Fontist::FontOperations::Pack.call("family.ttc", ["a.ttf", "b.ttf"])
+Fontist::FontOperations::Convert.call("a.ttf", "woff2", "a.woff2")
+Fontist::FontOperations::Subset.call("a.ttf", "sub.ttf", unicodes: "U+0041-005A")
+
+Fontist::Font.install("Lato", format: "woff2", subset_text: "Hello")
+----
+
+==== Variable-font instancing
+
+`--instance` installs a static instance of a variable font at the given axis
+values. Tags and ranges are checked against the font's `fvar` table; an
+unknown axis, an out-of-range value or a non-variable font is an error.
+
+[source,sh]
+----
+fontist install "Mona Sans" --instance wght=300
+fontist install "Mona Sans" --instance wght=300,wdth=90
+----
+
+[source,ruby]
+----
+Fontist::FontOperations::Instance.call("Font[wght].ttf", "light.ttf",
+                                       coordinates: { "wght" => 300 })
+Fontist::Font.install("Mona Sans", instance: "wght=300")
+----
+
+NOTE: Instancing needs a Fontisan release that includes static instancing
+(fontisan commit `b06fab3` or later; not in 0.4.46).
+
 === Install locations
 
 ==== General
@@ -1083,6 +1164,73 @@ Fontist::Fontconfig.remove(force: true) # do not fail if no config exists
 ----
 
 
+== Web fonts
+
+=== Google Fonts CSS URL: `fontist css`
+
+Prints the Google Fonts CSS2 URL for a Google family. It reads the formula
+only: no network access and no font installation.
+
+[source,sh]
+----
+$ fontist css "Source Sans 3" --styles 300,300i,600,600i
+https://fonts.googleapis.com/css2?family=Source+Sans+3:ital,wght@0,300;0,600;1,300;1,600&display=swap
+
+$ fontist css "Space Mono" --styles 400,700 --format link
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&amp;display=swap">
+----
+
+Options:
+
+`--styles`:: Comma-separated weights from 100 to 900; add `i` for italic
+(`300,300i,600`). Weights are checked against the styles the formula lists
+(for example Thin, ExtraLight, Light, Regular, Medium, SemiBold, Bold,
+ExtraBold, Black). Without `--styles` the URL asks for the provider default.
+`--display`:: `auto`, `block`, `swap` (default), `fallback` or `optional`.
+`--format`:: `url` (default) or `link` (an HTML `<link>` tag with `&` escaped
+as `&amp;`).
+
+Only the URL (or tag) goes to stdout. Errors go to stderr with a nonzero
+exit status, for an unknown family, a family that is not served by Google
+Fonts, an unlisted style or an invalid `--display`.
+
+The family name sent to Google is the formula's Google resource `family`; it
+is never derived from the formula name. So `Source Sans Pro` is not renamed to
+`Source Sans 3`: use the name the formula lists.
+
+From Ruby:
+
+[source,ruby]
+----
+Fontist::Css.url("Source Sans 3", styles: %w[300 300i 600 600i])
+Fontist::Css.link("Space Mono", styles: "400,700", display: "swap")
+----
+
+=== Self-hosted CSS: `fontist css --local`
+
+Builds a CSS bundle from fonts already installed by fontist: one file per
+style is copied into `--output-dir`, and `fonts.css` gets one `@font-face` per
+style (`font-family`, `src` with `format()`, `font-weight`, `font-style`).
+
+[source,sh]
+----
+$ fontist install "Space Mono"
+$ fontist css "Space Mono" --local --output-dir public/fonts \
+    --url-prefix /fonts --styles 400,700
+public/fonts/fonts.css
+----
+
+`--url-prefix`:: Prefix for the font URLs in `fonts.css` (default: relative
+file names).
+`--font-format`:: `woff2`, `woff`, `ttf` or `otf`. Selects an installed file of
+that format; the file must already be installed (for example with
+`fontist install "Space Mono" --format woff2`). There is no silent fallback
+to another format.
+
+Limits: only fonts installed in the fontist fonts directory are used, and no
+Google unicode-range subset files are produced. If the font is not installed
+the command tells you to run `fontist install`.
+
 == Platform-specific features
 
 === macOS supplementary fonts

data/fontist.gemspec

@@ -8,8 +8,10 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Ribose Inc."]
   spec.email         = ["open.source@ribose.com"]
 
+  # rubocop:disable Layout/LineLength
   spec.summary       = "Install openly-licensed fonts on Windows, Linux and Mac!"
   spec.description   = "Install openly-licensed fonts on Windows, Linux and Mac!"
+  # rubocop:enable Layout/LineLength
   spec.homepage      = "https://github.com/fontist/fontist"
   spec.license       = "BSD-2-Clause"
 
@@ -31,14 +33,13 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "down", "~> 5.0"
   spec.add_dependency "excavate", "~> 1.0", ">= 1.0.3"
-  spec.add_dependency "fontisan", "~> 0.4", ">= 0.4.9"
+  spec.add_dependency "fontisan", "~> 0.4", ">= 0.4.47"
   spec.add_dependency "fuzzy_match", "~> 2.1"
   spec.add_dependency "git", "~> 6.0"
-  spec.add_dependency "json", "~> 2.0"
   spec.add_dependency "lutaml-model", "~> 0.8.0"
   spec.add_dependency "marcel", "~> 1.0"
   spec.add_dependency "nokogiri", "~> 1.0"
-  spec.add_dependency "octokit", "~> 4.0"
+  spec.add_dependency "octokit", "~> 10.0"
   spec.add_dependency "paint", "~> 2.3"
   spec.add_dependency "parallel", "~> 1.24"
   spec.add_dependency "plist", "~> 3.0"

data/lib/fontist/cache/store.rb

@@ -40,7 +40,7 @@ module Fontist
         ensure_cache_dir
         entry = CacheEntry.new(value, ttl)
         write_entry(key, entry)
-      rescue TypeError, JSON::GeneratorError
+      rescue TypeError, Fontist::JSON::DumpError
         # Values outside the JSON type system (Time, Date, arbitrary
         # objects) skip the write and read back as a miss
         false
@@ -113,9 +113,9 @@ module Fontist
       def read_entry(key)
         return nil unless File.exist?(cache_path(key))
 
-        payload = JSON.parse(File.read(cache_path(key)))
+        payload = Fontist::JSON.parse(File.read(cache_path(key)))
         CacheEntry.new(payload["value"], expires_at: payload["expires_at"])
-      rescue JSON::ParserError, TypeError, EOFError
+      rescue Fontist::JSON::ParseError, TypeError, EOFError
         # Corrupted file - delete it and return nil. This can happen
         # on Windows when a file is read while being written, or when
         # cache files from previous runs are corrupted
@@ -137,9 +137,16 @@ module Fontist
       end
 
       def entry_payload(entry)
-        JSON.dump("version" => FORMAT_VERSION,
-                  "expires_at" => entry.expires_at,
-                  "value" => entry.value)
+        Fontist::JSON.dump("version" => FORMAT_VERSION,
+                           "expires_at" => entry.expires_at,
+                           "value" => entry.value)
+      rescue Fontist::JSON::DumpError
+        # Values outside the JSON type system (Time, Date, arbitrary
+        # objects) degrade to their string form, keeping the cache a
+        # best-effort store instead of a source of crashes
+        Fontist::JSON.dump("version" => FORMAT_VERSION,
+                           "expires_at" => entry.expires_at,
+                           "value" => entry.value.to_s)
       end
     end
   end

data/lib/fontist/cli.rb

@@ -29,6 +29,10 @@ module Fontist
     ERROR_TO_STATUS = {
       Fontist::Errors::UnsupportedFontError => [STATUS_NON_SUPPORTED_FONT_ERROR],
       Fontist::Errors::MissingFontError => [STATUS_MISSING_FONT_ERROR],
+      Fontist::FontOperations::Error => [STATUS_UNKNOWN_ERROR],
+      Fontist::Errors::CollectionIndexError => [STATUS_UNKNOWN_ERROR],
+      Fontist::Errors::UnsupportedTranscodeError => [STATUS_UNKNOWN_ERROR],
+      Fontist::Errors::SourceNotFoundError => [STATUS_UNKNOWN_ERROR],
       Fontist::Errors::SizeLimitError => [
         STATUS_SIZE_LIMIT_ERROR,
         :append,
@@ -119,8 +123,12 @@ module Fontist
     # Format selection options
     option :format,
            type: :string,
-           desc: "Font format to install (ttf, otf, woff, woff2, ttc, otc). " \
-                 "If format not available, will transcode from available formats."
+           desc: "Font format to install (ttf, otf, woff, woff2). " \
+                 "If format not available, will convert via Fontisan " \
+                 "(fails with an error unless --fallback-to-original)."
+    option :fallback_to_original,
+           type: :boolean,
+           desc: "If conversion fails, install the original format instead"
     option :variable_axes,
            type: :string,
            desc: "Variable axes to match (comma-separated, e.g., 'wght,wdth')"
@@ -140,7 +148,20 @@ module Fontist
     # Collection options
     option :collection_index,
            type: :numeric,
-           desc: "Extract specific font from TTC/OTC collection (0-indexed)"
+           desc: "Install only this member of a TTC/OTC collection " \
+                 "as a standalone font (0-indexed)"
+    # Subsetting options
+    option :subset_unicodes,
+           type: :string,
+           desc: "Keep only these codepoints (e.g., 'U+0020-007E,U+00E9')"
+    option :subset_text,
+           type: :string,
+           desc: "Keep only the glyphs for these characters"
+    # Variable-font instancing
+    option :instance,
+           type: :string,
+           desc: "Install a static instance of a variable font " \
+                 "(e.g., 'wght=300,wdth=90')"
     def install(*fonts)
       handle_class_options(options)
 
@@ -205,6 +226,18 @@ module Fontist
       handle_error(e)
     end
 
+    desc "pack OUTPUT FONT_FILE...",
+         "Bundle two or more font files into a TTC/OTC collection"
+    def pack(output, *files)
+      handle_class_options(options)
+
+      Fontist::FontOperations::Pack.call(output, files)
+      Fontist.ui.success("Collection written to #{output}")
+      STATUS_SUCCESS
+    rescue Fontist::Errors::GeneralError => e
+      handle_error(e)
+    end
+
     desc "uninstall/remove FONT", "Uninstall font by font or formula"
     def uninstall(font)
       handle_class_options(options)
@@ -270,14 +303,16 @@ module Fontist
                   finder.by_axes(axes)
                 elsif options[:category]
                   finder.by_category(options[:category])
+                elsif options[:format]
+                  finder.by_format(options[:format])
                 else
-                  error("Please specify --axes, --variable, or --category",
-                        STATUS_UNKNOWN_ERROR)
+                  error("Please specify --axes, --variable, --category " \
+                        "or --format", STATUS_UNKNOWN_ERROR)
                   return
                 end
 
       if options[:json]
-        Fontist.ui.say(JSON.pretty_generate(results.map(&:to_h)))
+        Fontist.ui.say(Fontist::JSON.pretty(results.map(&:to_h)))
       else
         print_find_results(results)
       end
@@ -287,6 +322,39 @@ module Fontist
       handle_error(e)
     end
 
+    desc "css FAMILY", "Print a Google Fonts CSS URL, or build local CSS"
+    long_desc <<-LONGDESC
+      Prints the Google Fonts CSS2 URL for FAMILY (no network, no install).
+      With --local, copies installed font files into --output-dir and writes
+      fonts.css there.
+    LONGDESC
+    option :styles, type: :string,
+                    desc: "Comma-separated weights, 'i' for italic " \
+                          "(e.g., 300,300i,600,600i)"
+    option :display, type: :string, default: "swap",
+                     desc: "font-display: auto, block, swap, fallback, optional"
+    option :format, type: :string, default: "url",
+                    desc: "Output: url or link (HTML <link> tag)"
+    option :local, type: :boolean, desc: "Build CSS from installed fonts"
+    option :output_dir, type: :string, desc: "Directory for --local output"
+    option :url_prefix, type: :string,
+                        desc: "URL prefix of font files in --local fonts.css"
+    option :font_format, type: :string,
+                         desc: "Font file format for --local (woff2, woff, " \
+                               "ttf, otf)"
+    def css(family)
+      handle_class_options(options)
+      return css_local(family) if options[:local]
+
+      css_google(family)
+    rescue Fontist::Css::UnknownFamilyError
+      css_error($!, STATUS_NON_SUPPORTED_FONT_ERROR)
+    rescue Fontist::Errors::MissingFontError
+      css_error($!, STATUS_MISSING_FONT_ERROR)
+    rescue Fontist::Css::Error
+      css_error($!, STATUS_UNKNOWN_ERROR)
+    end
+
     desc "update", "Update formulas"
     def update
       handle_class_options(options)
@@ -414,6 +482,38 @@ module Fontist
       STATUS_SUCCESS
     end
 
+    def css_google(family)
+      kind = options[:format]
+      unless %w[url link].include?(kind)
+        raise Fontist::Css::InvalidOptionError,
+              "Invalid format '#{kind}'. Use url or link."
+      end
+
+      $stdout.puts Fontist::Css.public_send(
+        kind, family, styles: options[:styles], display: options[:display]
+      )
+      success
+    end
+
+    def css_local(family)
+      unless options[:output_dir]
+        raise Fontist::Css::InvalidOptionError, "--local requires --output-dir."
+      end
+
+      path = Fontist::Css.local(family, output_dir: options[:output_dir],
+                                        url_prefix: options[:url_prefix],
+                                        styles: options[:styles],
+                                        font_format: options[:font_format])
+      $stdout.puts path
+      success
+    end
+
+    # Errors go to stderr so stdout carries only the result.
+    def css_error(exception, status)
+      warn exception.message
+      status
+    end
+
     def handle_error(exception)
       status, mode, message = ERROR_TO_STATUS[exception.class]
       raise exception unless status

data/lib/fontist/css/google_family.rb

@@ -0,0 +1,50 @@
+module Fontist
+  module Css
+    # Finds the Google formula for a family name and its canonical
+    # Google Fonts family (Resource#family; never derived from a slug).
+    module GoogleFamily
+      class << self
+        # @return [Array(Formula, String)] formula and canonical family
+        def resolve(family)
+          name = family.to_s.strip
+          matches = google_matches(candidates(name), name)
+          raise NotGoogleFamilyError, name if matches.empty?
+
+          keys = matches.map { |formula, _| formula.key }
+          raise AmbiguousFamilyError.new(name, keys) if keys.uniq.size > 1
+
+          matches.first
+        end
+
+        private
+
+        def candidates(name)
+          formulas = name.empty? ? [] : Formula.find_many(name)
+          raise UnknownFamilyError, name if formulas.empty?
+
+          formulas
+        end
+
+        def google_matches(formulas, name)
+          formulas.filter_map do |formula|
+            canonical = canonical_family(formula, name)
+            [formula, canonical] if canonical
+          end
+        end
+
+        def canonical_family(formula, name)
+          wanted = normalize(name)
+          Array(formula.resources).each do |resource|
+            next unless resource.source == "google"
+            return resource.family if normalize(resource.family) == wanted
+          end
+          nil
+        end
+
+        def normalize(text)
+          text.to_s.downcase.gsub(/[\s_-]+/, " ")
+        end
+      end
+    end
+  end
+end

data/lib/fontist/css/local.rb

@@ -0,0 +1,157 @@
+module Fontist
+  module Css
+    # Builds a self-hosted CSS bundle from fonts already installed by
+    # fontist: one copied file per style plus fonts.css with one @font-face
+    # per style. No downloads, installs or format conversion happen here.
+    class Local
+      CSS_FORMATS = {
+        "woff2" => "woff2",
+        "woff" => "woff",
+        "ttf" => "truetype",
+        "otf" => "opentype",
+      }.freeze
+
+      def initialize(family, output_dir:, url_prefix: nil, styles: nil,
+                     font_format: nil)
+        @family = family.to_s.strip
+        @output_dir = output_dir.to_s
+        @url_prefix = url_prefix.to_s
+        @styles = styles
+        @font_format = font_format&.to_s&.downcase
+        validate_font_format!
+      end
+
+      # @return [String] path of the written fonts.css
+      def call
+        raise UnknownFamilyError, @family if @family.empty?
+
+        entries = installed_entries
+        FileUtils.mkdir_p(@output_dir)
+        entries.each { |e| write_font(e) }
+        css_path = File.join(@output_dir, "fonts.css")
+        File.write(css_path, entries.map { |e| font_face(e) }.join("\n"))
+        css_path
+      end
+
+      private
+
+      def validate_font_format!
+        return if @font_format.nil? || CSS_FORMATS.key?(@font_format)
+
+        raise InvalidOptionError,
+              "Unsupported font format '#{@font_format}'. " \
+              "Use one of: #{CSS_FORMATS.keys.join(', ')}."
+      end
+
+      def installed_entries
+        formulas = Formula.find_many(@family)
+        raise UnknownFamilyError, @family if formulas.empty?
+
+        faces = formulas.filter_map { |formula| selected_faces(formula) }
+        raise UnknownFamilyError, @family if faces.empty?
+
+        faces.each do |candidate|
+          entries = locate(candidate)
+          return entries unless entries.empty?
+        end
+        raise Errors::MissingFontError, @family
+      end
+
+      # Faces of this family in the formula, narrowed to --styles.
+      def selected_faces(formula)
+        faces = Styles.faces(formula).select { |f| family?(f.style) }
+        return if faces.empty?
+
+        requested = Styles.parse(@styles)
+        return faces if requested.empty?
+
+        Styles.verify(@family, faces, requested)
+        faces.select { |f| requested.include?(f.tuple) }
+      end
+
+      def family?(style)
+        name = style.preferred_family_name || style.family_name
+        name.to_s.casecmp?(@family)
+      end
+
+      def locate(faces)
+        files = installed_files
+        faces.filter_map { |face| entry_for(face, files) }
+      end
+
+      # The installed file in the requested format, or the installed original
+      # to convert into it.
+      def entry_for(face, files)
+        path = files[wanted_name(face.style.font)]
+        return { path: path, face: face, ext: extension(path) } if path
+        return unless @font_format
+
+        original = files[File.basename(face.style.font.to_s).downcase]
+        return unless original
+
+        { path: original, face: face, ext: @font_format, convert: true }
+      end
+
+      def extension(path)
+        File.extname(path).delete(".")
+      end
+
+      def write_font(entry)
+        if entry[:convert]
+          FontOperations::Convert.call(entry[:path], @font_format,
+                                       target(entry))
+        else
+          FileUtils.cp(entry[:path], target(entry))
+        end
+      end
+
+      # A file name keyed by lowercase basename, so extension swaps match.
+      def wanted_name(font)
+        stem = File.basename(font.to_s, ".*")
+        ext = @font_format || File.extname(font.to_s).delete(".")
+        "#{stem}.#{ext}".downcase
+      end
+
+      def installed_files
+        patterns = Utils.font_file_patterns(Fontist.fonts_path.join("**").to_s)
+        patterns.flat_map { |p| Dir.glob(p) }.sort
+          .to_h { |path| [File.basename(path).downcase, path] }
+      end
+
+      def target(entry)
+        name = "#{File.basename(entry[:path], '.*')}.#{entry[:ext]}"
+        File.join(@output_dir, name)
+      end
+
+      def font_face(entry)
+        name = File.basename(target(entry))
+        face = entry[:face]
+        <<~CSS
+          @font-face {
+            font-family: "#{escape(@family)}";
+            src: url("#{escape(url_for(name))}") format("#{css_format(entry)}");
+            font-weight: #{face.weight};
+            font-style: #{face.italic ? 'italic' : 'normal'};
+          }
+        CSS
+      end
+
+      def url_for(name)
+        encoded = CGI.escape(name).gsub("+", "%20")
+        prefix = @url_prefix.chomp("/")
+        prefix.empty? ? encoded : "#{prefix}/#{encoded}"
+      end
+
+      def css_format(entry)
+        CSS_FORMATS.fetch(entry[:ext].downcase) do
+          raise InvalidOptionError,
+                "Cannot describe font file format '#{entry[:ext]}' in CSS."
+        end
+      end
+
+      def escape(text)
+        text.to_s.gsub(/[\\"]/) { |c| "\\#{c}" }.gsub(/\r?\n/, "\\A ")
+      end
+    end
+  end
+end