tone 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d3017ae0f1faf02c19825100422d443e068b901b29e6568c0b07d912452970f
+  data.tar.gz: 4d86df41de0b4f81cfac5924e065f7f17fa5e73e484e86c7071fcc5218fcb906
+SHA512:
+  metadata.gz: b5701133e078fa303fdeb3fa3be36a2b7e0059fe0f0b42f7dae2a5320ed6744dc51021ea19d0d2ec107ed15e312a0c1a8c0e0a8eef295f84afa600941e1a972d
+  data.tar.gz: 2f18052fcd993427dd8e0accf3df23ca0cfbfdb59b38c29f72930864025bb01c2837c9c7401312d69759a32235c536f5ccfaa4eaeea574a37b9245e6fa669582

data/LICENSE.adoc

@@ -0,0 +1,134 @@
+= Hippocratic License
+
+Version: 2.1.0.
+
+Purpose. The purpose of this License is for the Licensor named above to
+permit the Licensee (as defined below) broad permission, if consistent
+with Human Rights Laws and Human Rights Principles (as each is defined
+below), to use and work with the Software (as defined below) within the
+full scope of Licensor’s copyright and patent rights, if any, in the
+Software, while ensuring attribution and protecting the Licensor from
+liability.
+
+Permission and Conditions. The Licensor grants permission by this
+license ("License"), free of charge, to the extent of Licensor’s
+rights under applicable copyright and patent law, to any person or
+entity (the "Licensee") obtaining a copy of this software and
+associated documentation files (the "Software"), to do everything with
+the Software that would otherwise infringe (i) the Licensor’s copyright
+in the Software or (ii) any patent claims to the Software that the
+Licensor can license or becomes able to license, subject to all of the
+following terms and conditions:
+
+* Acceptance. This License is automatically offered to every person and
+entity subject to its terms and conditions. Licensee accepts this
+License and agrees to its terms and conditions by taking any action with
+the Software that, absent this License, would infringe any intellectual
+property right held by Licensor.
+* Notice. Licensee must ensure that everyone who gets a copy of any part
+of this Software from Licensee, with or without changes, also receives
+the License and the above copyright notice (and if included by the
+Licensor, patent, trademark and attribution notice). Licensee must cause
+any modified versions of the Software to carry prominent notices stating
+that Licensee changed the Software. For clarity, although Licensee is
+free to create modifications of the Software and distribute only the
+modified portion created by Licensee with additional or different terms,
+the portion of the Software not modified must be distributed pursuant to
+this License. If anyone notifies Licensee in writing that Licensee has
+not complied with this Notice section, Licensee can keep this License by
+taking all practical steps to comply within 30 days after the notice. If
+Licensee does not do so, Licensee’s License (and all rights licensed
+hereunder) shall end immediately.
+* Compliance with Human Rights Principles and Human Rights Laws.
+[arabic]
+. Human Rights Principles.
+[loweralpha]
+.. Licensee is advised to consult the articles of the United Nations
+Universal Declaration of Human Rights and the United Nations Global
+Compact that define recognized principles of international human rights
+(the "Human Rights Principles"). Licensee shall use the Software in a
+manner consistent with Human Rights Principles.
+.. Unless the Licensor and Licensee agree otherwise, any dispute,
+controversy, or claim arising out of or relating to (i) Section 1(a)
+regarding Human Rights Principles, including the breach of Section 1(a),
+termination of this License for breach of the Human Rights Principles,
+or invalidity of Section 1(a) or (ii) a determination of whether any Law
+is consistent or in conflict with Human Rights Principles pursuant to
+Section 2, below, shall be settled by arbitration in accordance with the
+Hague Rules on Business and Human Rights Arbitration (the "Rules");
+provided, however, that Licensee may elect not to participate in such
+arbitration, in which event this License (and all rights licensed
+hereunder) shall end immediately. The number of arbitrators shall be one
+unless the Rules require otherwise.
++
+Unless both the Licensor and Licensee agree to the contrary: (1) All
+documents and information concerning the arbitration shall be public and
+may be disclosed by any party; (2) The repository referred to under
+Article 43 of the Rules shall make available to the public in a timely
+manner all documents concerning the arbitration which are communicated
+to it, including all submissions of the parties, all evidence admitted
+into the record of the proceedings, all transcripts or other recordings
+of hearings and all orders, decisions and awards of the arbitral
+tribunal, subject only to the arbitral tribunal’s powers to take such
+measures as may be necessary to safeguard the integrity of the arbitral
+process pursuant to Articles 18, 33, 41 and 42 of the Rules; and (3)
+Article 26(6) of the Rules shall not apply.
+. Human Rights Laws. The Software shall not be used by any person or
+entity for any systems, activities, or other uses that violate any Human
+Rights Laws. "Human Rights Laws" means any applicable laws,
+regulations, or rules (collectively, "Laws") that protect human,
+civil, labor, privacy, political, environmental, security, economic, due
+process, or similar rights; provided, however, that such Laws are
+consistent and not in conflict with Human Rights Principles (a dispute
+over the consistency or a conflict between Laws and Human Rights
+Principles shall be determined by arbitration as stated above). Where
+the Human Rights Laws of more than one jurisdiction are applicable or in
+conflict with respect to the use of the Software, the Human Rights Laws
+that are most protective of the individuals or groups harmed shall
+apply.
+. Indemnity. Licensee shall hold harmless and indemnify Licensor (and
+any other contributor) against all losses, damages, liabilities,
+deficiencies, claims, actions, judgments, settlements, interest, awards,
+penalties, fines, costs, or expenses of whatever kind, including
+Licensor’s reasonable attorneys’ fees, arising out of or relating to
+Licensee’s use of the Software in violation of Human Rights Laws or
+Human Rights Principles.
+* Failure to Comply. Any failure of Licensee to act according to the
+terms and conditions of this License is both a breach of the License and
+an infringement of the intellectual property rights of the Licensor
+(subject to exceptions under Laws, e.g., fair use). In the event of a
+breach or infringement, the terms and conditions of this License may be
+enforced by Licensor under the Laws of any jurisdiction to which
+Licensee is subject. Licensee also agrees that the Licensor may enforce
+the terms and conditions of this License against Licensee through
+specific performance (or similar remedy under Laws) to the extent
+permitted by Laws. For clarity, except in the event of a breach of this
+License, infringement, or as otherwise stated in this License, Licensor
+may not terminate this License with Licensee.
+* Enforceability and Interpretation. If any term or provision of this
+License is determined to be invalid, illegal, or unenforceable by a
+court of competent jurisdiction, then such invalidity, illegality, or
+unenforceability shall not affect any other term or provision of this
+License or invalidate or render unenforceable such term or provision in
+any other jurisdiction; provided, however, subject to a court
+modification pursuant to the immediately following sentence, if any term
+or provision of this License pertaining to Human Rights Laws or Human
+Rights Principles is deemed invalid, illegal, or unenforceable against
+Licensee by a court of competent jurisdiction, all rights in the
+Software granted to Licensee shall be deemed null and void as between
+Licensor and Licensee. Upon a determination that any term or provision
+is invalid, illegal, or unenforceable, to the extent permitted by Laws,
+the court may modify this License to affect the original purpose that
+the Software be used in compliance with Human Rights Principles and
+Human Rights Laws as closely as possible. The language in this License
+shall be interpreted as to its fair meaning and not strictly for or
+against any party.
+* Disclaimer. TO THE FULL EXTENT ALLOWED BY LAW, THIS SOFTWARE COMES
+"AS IS," WITHOUT ANY WARRANTY, EXPRESS OR IMPLIED, AND LICENSOR AND
+ANY OTHER CONTRIBUTOR SHALL NOT BE LIABLE TO ANYONE FOR ANY DAMAGES OR
+OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+OR THIS LICENSE, UNDER ANY KIND OF LEGAL CLAIM.
+
+This Hippocratic License is an link:https://ethicalsource.dev[Ethical Source license] and is offered
+for use by licensors and licensees at their own risk, on an "AS IS" basis, and with no warranties
+express or implied, to the maximum extent permitted by Laws.

data/README.adoc

@@ -0,0 +1,453 @@
+:toc: macro
+:toclevels: 5
+:figure-caption!:
+
+:amazing_print_link: link:https://github.com/amazing-print/amazing_print[Amazing Print]
+:pattern_matching_link: link:https://alchemists.io/articles/ruby_pattern_matching[pattern matching]
+
+= Tone
+
+Provides a customizable link:https://stackoverflow.com/questions/4842424/list-of-ansi-color-escape-sequences[ANSI] text colorizer for your terminal. This allows you to encode plain text that renders as colorized output. This is great for enhancing Command Line Interfaces (CLIs) and terminal output in general.
+
+toc::[]
+
+== Features
+
+* Provides default styles with multiple options for unique combinations.
+* Provides a single object for encoding and decoding colorized text.
+* Provides aliasing of color configurations.
+* Provides quick access to default and aliased styles.
+
+== Requirements
+
+. link:https://www.ruby-lang.org[Ruby].
+
+== Setup
+
+To install, run:
+
+[source,ruby]
+----
+gem install tone
+----
+
+You can also add the gem directly to your project (preferred):
+
+[source,ruby]
+----
+bundle add tone
+----
+
+Once the gem is installed, you only need to require it:
+
+```
+require "tone"
+```
+
+== Usage
+
+Basic usage is as follows:
+
+[source,ruby]
+----
+tone = Tone.new
+tone["Success!", :green]  # "\e[32mSuccess!\e[0m"
+----
+
+There is a lot more you can do with this gem so the following sections will delve into the specifics.
+
+=== Encode
+
+As you saw earlier, you can encode plain text as colorized text using `+#[]+`. Use of the `+#[]+` method is an _alias_ to the longer `#encode` method. This allows you to use minimal syntax to create colorized text. Here's a few more examples:
+
+[source,ruby]
+----
+tone = Tone.new
+
+# With symbols.
+tone["Success", :black, :on_green]    # "\e[30;42mSuccess\e[0m"
+
+# With strings.
+tone["Success", "black", "on_green"]  # "\e[30;42mSuccess\e[0m"
+
+# With no styles.
+tone["Success"]                       # "Success"
+
+# With any object that responds to `#to_str` or `#to_s`.
+tone[Object.new, :green]              # "\e[32m#<Object:0x000000010f095668>\e[0m"
+
+# With nil.
+tone[nil]                             # ""
+
+# With interspersed nils (nils are ignored).
+tone["Success", nil, :green, nil]     # "\e[32mSuccess\e[0m"
+----
+
+The first argument is the text you want to encode/colorize. This can be a word, phrase, paragraph, or entire document. All arguments that follow after the first argument are _style_ arguments which allow you to style the color of your text as you see fit. In this case, the `"Success"` text will use a _black foreground_ on a _green background_. The styles available for you to use will be explained shortly, though. For now, know that `+#[]+` is shorthand for `#encode` so any of the above examples could be replaced with `#encode` messages. Example:
+
+[source,ruby]
+----
+tone = Tone.new
+tone.encode "Success", :black, :on_green  # "\e[30;42mSuccess\e[0m"
+----
+
+Both methods are available to use depending on your preference.
+
+=== Decode
+
+Once your text has been encoded with colors, it can be nice to decode the colorized text back to plain text along with additional metadata. This is helpful -- as an example -- for testing purposes since you might not always want to deal with the hard to read escape characters. If we build upon the examples from the _Encode_ section, we can decode our colorized text into plain text with extra metadata:
+
+[source,ruby]
+----
+tone = Tone.new
+
+tone.decode "\e[30;42mSuccess\e[0m"  # [["Success", :black, :on_green]]
+tone.decode "\e[37;41mFailure\e[0m"  # [["Failure", :white, :on_red]]
+----
+
+Notice we get an array of sub arrays which mimic the original arguments passed to `#encode`. This allows you to encode and decode with minimal effort. Here's a more complex example where a sentence is used and formatted with the {amazing_print_link} gem:
+
+[source,ruby]
+----
+tone = Tone.new
+ap tone.decode("We turned a \e[37;41mfailure\e[0m into a \e[30;42msuccess\e[0m!")
+
+# [
+#   [
+#     "We turned a "
+#   ],
+#   [
+#     "failure",
+#     :white,
+#     :on_red
+#   ],
+#   [
+#     " into a "
+#   ],
+#   [
+#     "success",
+#     :black,
+#     :on_green
+#   ],
+#   [
+#     "!"
+#   ]
+# ]
+----
+
+For plain text, you get a single element array but for colorized text, it will be broken down into an array of arguments. This allows you to easily iterate over this structure for parsing, transformation, or {pattern_matching_link} purposes.
+
+Here's another example where a paragraph is used:
+
+[source,ruby]
+----
+tone = Tone.new
+
+paragraph = <<~CONTENT.strip
+  Yesterday \e[30;42mwent well\e[0m
+  but tomorrow will be \e[37;41mmore challenging\e[0m.
+CONTENT
+
+ap tone.decode(paragraph)
+
+# [
+#   [
+#     "Yesterday "
+#   ],
+#   [
+#     "went well",
+#     :black,
+#     :on_green
+#   ],
+#   [
+#     "\nbut tomorrow will be "
+#   ],
+#   [
+#     "more challenging",
+#     :white,
+#     :on_red
+#   ],
+#   [
+#     "."
+#   ]
+# ]
+----
+
+=== Defaults
+
+To display defaults, use:
+
+``` ruby
+tone = Tone.new
+tone.defaults
+```
+
+The above will output something similar to what you see below (minus the categorization) of key and value which will allow you to pick and choose the style or combination of styles you desire.
+
+* *Styles*
+** `clear`
+** `bold`
+** `dim`
+** `italic`
+** `underline`
+** `inverse`
+** `hidden`
+** `strikethrough`
+* *Foregrounds*
+** `black`
+** `red`
+** `green`
+** `yellow`
+** `blue`
+** `purple`
+** `cyan`
+** `white`
+** `bright_black`
+** `bright_red`
+** `bright_green`
+** `bright_yellow`
+** `bright_blue`
+** `bright_purple`
+** `bright_cyan`
+** `bright_white`
+* *Backgrounds*
+** `on_black`
+** `on_red`
+** `on_green`
+** `on_yellow`
+** `on_blue`
+** `on_purple`
+** `on_cyan`
+** `on_white`
+** `on_bright_black`
+** `on_bright_red`
+** `on_bright_green`
+** `on_bright_yellow`
+** `on_bright_blue`
+** `on_bright_purple`
+** `on_bright_cyan`
+** `on_bright_white`
+
+These are the defaults for which you can mix-n-match as desired to produce colorful output. For example, if you want black text on a green background with an underline, you could use:
+
+```
+tone = Tone.new
+puts tone["Success!", :black, :on_green, :strikethrough]
+```
+
+==== Codes
+
+For situations where you'd like to find a code (or codes) for a symbol you can use the following:
+
+[source,ruby]
+----
+tone = Tone.new
+
+tone.find_code :green                # 32
+tone.find_code :bogus                # nil
+tone.find_codes :green               # [32]
+tone.find_codes :red, :green, :blue  # [31, 32, 34]
+tone.find_codes :bogus, :invalid     # [nil, nil]
+----
+
+==== Symbols
+
+Much like with the codes, mentioned above, you can find a symbol (or symbols) for a code too:
+
+[source,ruby]
+----
+tone = Tone.new
+
+tone.find_symbol 32           # :green
+tone.find_symbol 666          # nil
+tone.find_symbols 32          # [:green]
+tone.find_symbols 31, 32, 34  # [:red, :green, :blue]
+tone.find_symbols 666, 999    # [nil, nil]
+----
+
+=== Aliases
+
+You can alias combinations of default styles with a descriptive name for shorthand reuse. This allows you to reduce duplicated effort and speed up your workflow. Here are a few examples:
+
+[source,ruby]
+----
+tone = Tone.new
+tone.add_alias :success, :black, :on_green
+tone.add_alias :failure, :white, :on_red
+
+tone["Success!", :success]  # "\e[30;42mSuccess!\e[0m"
+tone["Failure!", :failure]  # "\e[37;41mFailure!\e[0m"
+----
+
+Notice that the first argument is your alias and _all arguments after the first argument_ is the list of styles. Once added, both the `:success` and `:failure` aliases can immediately be used. You can also add multiple aliases, at once, by chaining your messages:
+
+``` ruby
+tone = Tone.new
+           .add_alias(:success, :black, :on_green)
+           .add_alias :failure, :white, :on_red
+
+tone["Success!", :success]  # "\e[30;42mSuccess!\e[0m"
+tone["Failure!", :failure]  # "\e[37;41mFailure!\e[0m"
+```
+
+Aliases -- and associated styles -- can be symbols or strings. The following, despite using strings, is identical to the above:
+
+[source,ruby]
+----
+tone = Tone.new
+           .add_alias("success", "black", "on_green")
+           .add_alias "failure", "white", "on_red"
+
+tone["Success!", :success]  # "\e[30;42mSuccess!\e[0m"
+tone["Failure!", :failure]  # "\e[37;41mFailure!\e[0m"
+----
+
+To see the list of all aliases added, use:
+
+[source,ruby]
+----
+tone = Tone.new.add_alias(:success, :black, :on_green).add_alias :failure, :white, :on_red
+ap tone.aliases
+
+# {
+#   :success => [
+#     :black,
+#     :on_green
+#   ],
+#   :failure => [
+#     :white,
+#     :on_red
+#   ]
+# }
+----
+
+To get a specific alias, use:
+
+[source,ruby]
+----
+tone = Tone.new.add_alias :success, :black, :on_green
+tone.get_alias :success
+
+# [:black, :on_green]
+----
+
+In the case of a default, you'll only get back the given key:
+
+[source,ruby]
+----
+Tone.new.get_alias :green  # :green
+----
+
+=== Errors
+
+There are several checks performed which might result in a `Tone::Error` if not properly used. Here's a few examples of what you might see.
+
+[source,ruby]
+----
+tone = Tone.new
+
+tone.add_alias :bogus
+# Alias must have styles: :bogus. (Tone::Error)
+
+tone.add_alias :bogus, nil
+# Alias must have styles: :bogus. (Tone::Error)
+
+tone.add_alias :red, :red
+# Alias mustn't duplicate (override) default: :red. (Tone::Error)
+
+tone.add_alias :bogus, :invalid
+# Invalid style (:invalid) for key (:bogus). (Tone::Error)
+
+tone.add_alias :success, :black, :on_green
+tone.add_alias :success, :black, :on_green
+# Duplicate alias detected (already exists): :success. (Tone::Error)
+
+tone.get_alias nil
+# Invalid alias or default: nil. (Tone::Error)
+
+tone.get_alias :bogus
+# Invalid alias or default: :bogus. (Tone::Error)
+----
+
+=== Guidelines
+
+The following are worth considering, when using this gem, to help keep your implementation consistent.
+
+Order your arguments by style, foreground, and background when encoding:
+
+[source,ruby]
+----
+# No
+tone["test, :underline, :on_black, :white]
+tone["test, :white, :underline, :on_black]
+tone["test, :on_black, :white, :underline]
+
+# Yes
+tone["test, :underline, :white, :on_black]
+----
+
+Order your arguments by style, foreground, and background when adding aliases:
+
+[source,ruby]
+----
+# No
+tone.add_alias :demo, :underline, :on_black, :white
+tone.add_alias :demo, :white, :underline, :on_black
+tone.add_alias :demo, :on_black, :white, :underline
+
+# Yes
+tone.add_alias :demo, :underline, :white, :on_black
+----
+
+These are not hard requirements but these little touches will help improve readability. 🎉
+
+== Development
+
+To contribute, run:
+
+[source,bash]
+----
+git clone https://github.com/bkuhlmann/tone
+cd tone
+bin/setup
+----
+
+You use the IRB console for direct access to all objects:
+
+[source,bash]
+----
+bin/console
+----
+
+Lastly, there is a `bin/show` script which can be run to display all default styles for quick visual convenience:
+
+[source,bash]
+----
+bin/show
+----
+
+== Tests
+
+To test, run:
+
+[source,bash]
+----
+bin/rake
+----
+
+== link:https://alchemists.io/policies/license[License]
+
+== link:https://alchemists.io/policies/security[Security]
+
+== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]
+
+== link:https://alchemists.io/policies/contributions[Contributions]
+
+== link:https://alchemists.io/projects/tone/versions[Versions]
+
+== link:https://alchemists.io/community[Community]
+
+== Credits
+
+* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].
+* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].

data/lib/tone/aliaser.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "refinements/arrays"
+
+module Tone
+  # Allows storage of custom custom which can be referenced when colorizing text.
+  class Aliaser
+    using Refinements::Arrays
+
+    attr_reader :defaults
+
+    def initialize defaults: DEFAULTS
+      @defaults = defaults
+      @custom = {}
+    end
+
+    def get key
+      symbol = String(key).to_sym
+
+      custom.fetch symbol do
+        return key if defaults.key? symbol
+
+        usage = defaults.keys.append(*custom.keys).map(&:inspect).to_sentence conjunction: "and/or"
+
+        fail Error, "Invalid alias or default: #{key.inspect}. Use: #{usage}."
+      end
+    end
+
+    def add(key, *styles)
+      fail Error, "Alias must have styles: #{key.inspect}." if styles.tap(&:compact!).empty?
+
+      custom[key.to_sym] = validate key, styles.map(&:to_sym)
+      self
+    end
+
+    def to_h = custom.dup
+
+    private
+
+    attr_reader :custom
+
+    def validate key, styles
+      check_duplicate key
+      styles.each { |style| check_style key, style }
+      styles
+    end
+
+    def check_duplicate key
+      kind = key.inspect
+
+      fail Error, "Duplicate alias detected (already exists): #{kind}." if custom.key? key
+      fail Error, "Alias mustn't duplicate (override) default: #{kind}." if defaults.key? key
+    end
+
+    def check_style key, style
+      defaults.fetch style do
+        usage = defaults.keys.map(&:inspect).to_sentence conjunction: "and/or"
+
+        fail Error, "Invalid style (#{style.inspect}) for key (#{key.inspect}). Use: #{usage}."
+      end
+    end
+  end
+end

data/lib/tone/client.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Tone
+  # The primary interface for working with colorized text.
+  class Client
+    def initialize enabled: $stdout.tty?, container: Tone::CONTAINER
+      @aliaser = container.fetch(:aliaser).new defaults: container.fetch(:defaults)
+      @encoder = container.fetch(:encoder).new(aliaser:, enabled:)
+      @decoder = container.fetch(:decoder).new defaults: aliaser.defaults
+    end
+
+    def defaults = aliaser.defaults
+
+    def aliases = aliaser.to_h
+
+    def add_alias(...)
+      aliaser.add(...)
+      self
+    end
+
+    def get_alias(...) = aliaser.get(...)
+
+    def encode(...) = encoder.call(...)
+
+    alias [] encode
+
+    def decode(...) = decoder.call(...)
+
+    def find_code(key) = defaults[key]
+
+    def find_codes(*keys) = defaults.values_at(*keys)
+
+    def find_symbol(code) = defaults.invert[code]
+
+    def find_symbols(*codes) = defaults.invert.values_at(*codes)
+
+    private
+
+    attr_reader :aliaser, :encoder, :decoder
+  end
+end

data/lib/tone/configuration/defaults.yml

@@ -0,0 +1,44 @@
+clear: 0
+bold: 1
+dim: 2
+italic: 3
+underline: 4
+inverse: 7
+hidden: 8
+strikethrough: 9
+
+black: 30
+red: 31
+green: 32
+yellow: 33
+blue: 34
+purple: 35
+cyan: 36
+white: 37
+
+bright_black: 90
+bright_red: 91
+bright_green: 92
+bright_yellow: 93
+bright_blue: 94
+bright_purple: 95
+bright_cyan: 96
+bright_white: 97
+
+on_black: 40
+on_red: 41
+on_green: 42
+on_yellow: 43
+on_blue: 44
+on_purple: 45
+on_cyan: 46
+on_white: 47
+
+on_bright_black: 100
+on_bright_red: 101
+on_bright_green: 102
+on_bright_yellow: 103
+on_bright_blue: 104
+on_bright_purple: 105
+on_bright_cyan: 106
+on_bright_white: 107

data/lib/tone/configuration/loader.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Tone
+  module Configuration
+    # Loads the default configuration into memory as a frozen hash.
+    class Loader
+      def initialize path: Pathname("#{__dir__}/defaults.yml")
+        @path = path
+      end
+
+      def call = YAML.safe_load(path.read, symbolize_names: true).freeze
+
+      private
+
+      attr_reader :path
+    end
+  end
+end

data/lib/tone/decoder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Tone
+  # Decodes color encoded text into metadata (hash).
+  class Decoder
+    PATTERN = /
+      \e\[              # Start prefix.
+      (?<codes>[\d;]+)  # Style codes.
+      m                 # Start suffix.
+      (?<text>.+?)      # Lazy text.
+      \e\[0m            # Stop.
+    /mx
+
+    def initialize pattern: PATTERN, defaults: DEFAULTS, client: StringScanner
+      @pattern = pattern
+      @defaults = defaults
+      @client = client
+      @prefix_pattern = /.*#{pattern}/m
+    end
+
+    def call(text) = scan client.new(String(text))
+
+    private
+
+    attr_reader :pattern, :defaults, :client, :prefix_pattern
+
+    def scan scanner, collection: []
+      until scanner.eos?
+        result = scanner.scan_until pattern
+
+        return collection.append [scanner.string[scanner.rest]] unless result
+
+        normal = scanner.pre_match.sub prefix_pattern, ""
+
+        collection << [normal] unless normal.empty?
+        collection << extract_captures(scanner)
+      end
+
+      collection
+    end
+
+    def extract_captures scanner
+      codes, text = scanner.captures
+      [text, *symbolize(codes)]
+    end
+
+    def symbolize(codes) = defaults.invert.values_at(*String(codes).split(";").map(&:to_i))
+  end
+end

data/lib/tone/encoder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "refinements/arrays"
+
+module Tone
+  # Encodes plain text as colorized text.
+  class Encoder
+    using Refinements::Arrays
+
+    def initialize aliaser: Aliaser.new, enabled: $stdout.tty?
+      @aliaser = aliaser
+      @enabled = enabled
+    end
+
+    def call(text, *styles)
+      return "" if String(text).empty?
+
+      !enabled || styles.tap(&:compact!).empty? ? text : "#{start(*styles)}#{text}#{stop}"
+    end
+
+    private
+
+    attr_reader :aliaser, :enabled
+
+    def start(*styles) = %(\e[#{escape(*styles)}m)
+
+    def stop = "\e[#{defaults.fetch :clear}m"
+
+    def escape(*styles)
+      styles.reduce([]) { |expansion, key| expansion.append(*aliaser.get(key)) }
+            .map { |key| defaults[key.to_sym] }
+            .join ";"
+    end
+
+    def defaults = aliaser.defaults
+  end
+end

data/lib/tone/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Tone
+  # Root error class for gem.
+  class Error < StandardError
+  end
+end

data/lib/tone.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+Zeitwerk::Loader.for_gem.setup
+
+# Main namespace.
+module Tone
+  DEFAULTS = Configuration::Loader.new.call
+  CONTAINER = {defaults: DEFAULTS, aliaser: Aliaser, encoder: Encoder, decoder: Decoder}.freeze
+
+  def self.new(...) = Client.new(...)
+end

data/tone.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = "tone"
+  spec.version = "0.0.0"
+  spec.authors = ["Brooke Kuhlmann"]
+  spec.email = ["brooke@alchemists.io"]
+  spec.homepage = "https://alchemists.io/projects/tone"
+  spec.summary = "A customizable ANSI text colorizer for your terminal."
+  spec.license = "Hippocratic-2.1"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/bkuhlmann/tone/issues",
+    "changelog_uri" => "https://alchemists.io/projects/tone/versions",
+    "documentation_uri" => "https://alchemists.io/projects/tone",
+    "funding_uri" => "https://github.com/sponsors/bkuhlmann",
+    "label" => "Tone",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => "https://github.com/bkuhlmann/tone"
+  }
+
+  spec.signing_key = Gem.default_key_path
+  spec.cert_chain = [Gem.default_cert_path]
+
+  spec.required_ruby_version = "~> 3.2"
+  spec.add_dependency "refinements", "~> 10.0"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+
+  spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
+  spec.files = Dir["*.gemspec", "lib/**/*"]
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: tone
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Brooke Kuhlmann
+autorequire:
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIEeDCCAuCgAwIBAgIBATANBgkqhkiG9w0BAQsFADBBMQ8wDQYDVQQDDAZicm9v
+  a2UxGjAYBgoJkiaJk/IsZAEZFgphbGNoZW1pc3RzMRIwEAYKCZImiZPyLGQBGRYC
+  aW8wHhcNMjMwMzIyMTYxNDQxWhcNMjUwMzIxMTYxNDQxWjBBMQ8wDQYDVQQDDAZi
+  cm9va2UxGjAYBgoJkiaJk/IsZAEZFgphbGNoZW1pc3RzMRIwEAYKCZImiZPyLGQB
+  GRYCaW8wggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQCro8tj5/E1Hg88
+  f4qfiwPVd2zJQHvdYt4GHVvuHRRgx4HGhJuNp+4BId08RBn7V6V1MW6MY3kezRBs
+  M+7QOQ4b1xNLTvY7FYQB1wGK5a4x7TTokDrPYQxDB2jmsdDYCzVbIMrAvUfcecRi
+  khyGZCdByiiCl4fKv77P12tTT+NfsvXkLt/AYCGwjOUyGKTQ01Z6eC09T27GayPH
+  QQvIkakyFgcJtzSyGzs8bzK5q9u7wQ12MNTjJoXzW69lqp0oNvDylu81EiSUb5S6
+  QzzPxZBiRB1sgtbt1gUbVI262ZDq1gR+HxPFmp+Cgt7ZLIJZAtesQvtcMzseXpfn
+  hpmm0Sw22KGhRAy/mqHBRhDl5HqS1SJp2Ko3lcnpXeFResp0HNlt8NSu13vhC08j
+  GUHU9MyIXbFOsnp3K3ADrAVjPWop8EZkmUR3MV/CUm00w2cZHCSGiXl1KMpiVKvk
+  Ywr1gd2ZME4QLSo+EXUtLxDUa/W3xnBS8dBOuMMz02FPWYr3PN8CAwEAAaN7MHkw
+  CQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0OBBYEFAFgmv0tYMZnItuPycSM
+  F5wykJEVMB8GA1UdEQQYMBaBFGJyb29rZUBhbGNoZW1pc3RzLmlvMB8GA1UdEgQY
+  MBaBFGJyb29rZUBhbGNoZW1pc3RzLmlvMA0GCSqGSIb3DQEBCwUAA4IBgQAX+EGY
+  9RLYGxF1VLZz+G1ACQc4uyrCB6kXwI06kzUa5dF9tPXqTX9ffnz3/W8ck2IQhKzu
+  MKO2FVijzbDWTsZeZGglS4E+4Jxpau1lU9HhOIcKolv6LeC6UdALTFudY+GLb8Xw
+  REXgaJkjzzhkUSILmEnRwEbY08dVSl7ZAaxVI679vfI2yapLlIwpbBgmQTiTvPr3
+  qyyLUno9flYEOv9fmGHunSrM+gE0/0niGTXa5GgXBXYGS2he4LQGgSBfGp/cTwMU
+  rDKJRcusZ12lNBeDfgqACz/BBJF8FLodgk6rGMRZz7+ZmjjHEmpG5bQpR6Q2BuWL
+  XMtYk/QzaWuhiR7pWjiF8jbdd7RO6or0ohq7iFkokz/5xrtQ/vPzU2RQ3Qc6YaKw
+  3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
+  gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
+  -----END CERTIFICATE-----
+date: 2023-04-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: refinements
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description:
+email:
+- brooke@alchemists.io
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.adoc
+- LICENSE.adoc
+files:
+- LICENSE.adoc
+- README.adoc
+- lib/tone.rb
+- lib/tone/aliaser.rb
+- lib/tone/client.rb
+- lib/tone/configuration/defaults.yml
+- lib/tone/configuration/loader.rb
+- lib/tone/decoder.rb
+- lib/tone/encoder.rb
+- lib/tone/error.rb
+- tone.gemspec
+homepage: https://alchemists.io/projects/tone
+licenses:
+- Hippocratic-2.1
+metadata:
+  bug_tracker_uri: https://github.com/bkuhlmann/tone/issues
+  changelog_uri: https://alchemists.io/projects/tone/versions
+  documentation_uri: https://alchemists.io/projects/tone
+  funding_uri: https://github.com/sponsors/bkuhlmann
+  label: Tone
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/bkuhlmann/tone
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A customizable ANSI text colorizer for your terminal.
+test_files: []