oppen 0.9.7 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b656616fe07cf5b29b8dfa43f0b72ed6dbf80c56a9ca6790745a8db27f058ed7
-  data.tar.gz: 3d46ddc3a703d029ac22460ac504cf2928f95d804d32e0266f0de7ffbbfd3359
+  metadata.gz: e53fd2f0875228c91da4aaa2259d7b1bf18e0561284513e57181cb6c260ba610
+  data.tar.gz: 82c1776d841d6eef2d2071fc923b4864e23e2e68e079fa6caec36b7cca23ffbc
 SHA512:
-  metadata.gz: 7b69f0365a507dc9fca546cbfea064593a48d0d85140cd894ed2ff256e13c4c0e772bf9e0d2b29f9eefd9121c8b3adf03da93137c15b3c9570f6a7e49ed435b2
-  data.tar.gz: aa608fa2238dc8eea6bf3ce5d03f10e6f8059eda98c02d1e53fa06f9ac9301b03b42e54b38ed4f945c28766c4959b441cc190b76f0f176a72c7f52967096258a
+  metadata.gz: 87f3293a723b93c82532045aafe0dd699b6d7ac754893d51ff338448550187f27d75d7bea12fd4035be3f765de660605c56ac431460785387b47b6955b2805bb
+  data.tar.gz: 9928e9536e2fb193150fb32d000abf5e5b0017cbbecab050b2b064f14847f72b24ac573ea4779d2fe0bd2f5ac4f5b1ef04a7b1341bdc36e9b74bd652aa3b43ce

data/README.md

@@ -22,17 +22,12 @@ transition from `ruby/prettyprint` to this gem.
 
 `Wadler` is implemented on top of `Oppen`, and it provides more options than
 `ruby/prettyprint`, notably:
-1. Consistent and inconsistent breaking.
-1. Explicit breaking, which is achievable in `ruby/prettyprint` with some
-monkeypatching.
-
-> [!CAUTION]
-> This is still under development.
-
-## Usage
-
-> [!WARNING]
-> Lands when the APIs are stable.
+1. [Consistent](examples/wadler_group/consistent.rb) and [inconsistent](examples/wadler_group/inconsistent.rb) breaking.
+1. [Explicit breaking](examples/wadler_break_and_breakable/break.rb), which is achievable in `ruby/prettyprint` with some monkeypatching.
+1. [Trimming of trailing whitespaces](examples/oppen_and_wadler_customization/whitespace.rb).
+1. [Display a `String` on line break](examples/wadler_break_and_breakable/line_continuation.rb).
+1. A bunch of helper methods to simplify common patterns like [surrounding](examples/wadler_utils/surround.rb) or
+[separating](examples/wadler_utils/surround.rb) tokens.
 
 ## Oppen vs Wadler
 
@@ -40,34 +35,109 @@ monkeypatching.
 and it's not calling ruby's `prettyprint`.
 
 Both implementations have their use cases:
-1. Oppen gives more control over tokens sent to the printer.
-1. Wadler gives a more _"functional"_ API, which is far nicer to work with.
+- Oppen gives more control over tokens sent to the printer.
+- Wadler gives a more _"functional"_ API, which is far nicer to work with.
 
 That being said, both APIs in this gem can achieve the same results, especially
 on consistent and inconsistent breaking.
 
-## Noteworthy details
-
-### Difference with Oppen's original algorithm
-
-1. We took liberty to rename functions to make the API more modern and closer to
+## Oppen's API Example
+
+```ruby
+tokens = [
+  Oppen.begin_inconsistent,
+  Oppen.string('Hello'),
+  Oppen.break(', '),
+  Oppen.string('World!'),
+  Oppen.line_break,
+  Oppen.string('How are you doing?'),
+  Oppen.end,
+  Oppen.eof,
+]
+
+puts Oppen.print(tokens:)
+# Hello, World!
+#   How are you doing?
+```
+
+## Wadler's API Example
+
+```ruby
+out = Oppen::Wadler.new(width: 20)
+
+out.group(indent: 2) {
+  out.group {
+    out.text('def').breakable.text('foo')
+  }
+  out.parens_break_none {
+    out.separate(%w[bar baz bat qux], ',', break_type: :inconsistent) { |param|
+      out.text(param)
+    }
+  }
+}
+out.group(indent: 2) {
+  out
+    .break
+    .nest(indent: 2) {
+      out
+        .text('puts')
+        .breakable(line_continuation: ' \\')
+        .text('42')
+  }
+}
+out.break.text('end')
+
+puts out.output
+# def foo(bar, baz,
+#   bat, qux)
+#   puts \
+#     42
+# end
+```
+
+## More Examples
+
+An easy way to add colors to the output on the terminal is wrap `oppen` and expose your own vocabulary:
+
+```ruby
+require 'colored'
+class ColoredTty
+  KW_PALETTE = { Hello: :red, World: :green }.freeze
+  def initialize(...) = @out = Oppen::Wadler.new(...)
+  def breakable(...) = @out.breakable(...) && self
+  def keyword(value, width: value.length) = @out.text(value.send(KW_PALETTE[value.to_sym] || :white), width:) && self
+  def output = @out.output
+  def text(...) = @out.text(...) && self
+end
+
+out = ColoredTty.new(width: 12)
+out.keyword('Hello').breakable.text('World')
+
+puts out.output
+# \e[31mHello\e[0m World
+```
+
+The same idea can be applied an adapted to make an HTML printer; all you need to take care of is the correct width of the text to preserve the width of the text and get an output identical to that of the tty colored printer.
+
+Check out the [examples/](examples/README.md) folder for more details on how to use the Oppen and Wadler APIs.
+
+## Difference With Oppen's Original Algorithm
+
+1. We took the liberty to rename functions to make the API more modern and closer to
 what we expect when writing Ruby code.  All correspondences with the algorithm
 as described in Oppen's paper are noted in the comments of classes and methods.
 1. We do not raise exceptions when we overflow the margin. The only exceptions
 that we raise indicate a bug in the implementation. Please report them.
+1. The stacks described by the algorithm do not have a fixed size in our
+implementation: we upsize them when they are full.
+1. We can optionally trim trailing whitespaces (this feature is on by default for the `Wadler` API).
+1. We added support for an additional new line anchors, see [examples/configs/indent_anchor.rb](examples/configs/indent_anchor.rb).
+1. We added support for eager printing of `groups`; see [examples/configs/eager_print.rb](examples/configs/eager_print.rb).
+1. We introduced a new token (`Whitespace`) and added more customizations to one of the originals (`Break`).
 
-### Difference with `ruby/prettyprint`
-
-Oppen's algorithm and `ruby/prettyprint` do not have the same starting positions
-for a group's indentation. That's why you need to pay particular attention to
-calls for `nest`; you might want to decrease them by `1` if you care about keeping
-the same behavior.
-
-This is what we do in our test suite to verify the correspondence of the `Wadler`
-API and the `ruby/prettyprint`. We decided to shift the burden to the user because
-we think that the deicision taken by `ruby/prettyprint` does not suit us.
+For more insight on how Oppen's algorithm works, check out [docs/oppen_algorithm.md](docs/oppen_algorithm.md).
 
-## Related projects
+## Related Projects
 
 1. [`ruby/prettyprint`](https://github.com/ruby/prettyprint)
 1. [rustc implementation](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast_pretty/pp/index.html)

data/lib/oppen/mixins.rb

@@ -4,70 +4,68 @@ module Oppen
   # Mixins.
   module Mixins
     # Rotates circular array and triples its size.
-    # This method is not for public use.
     #
-    # @param arr [Array]
-    # @param offset [Integer] Rotation amount
+    # @!visibility private
+    # @note This method is not for public use.
     #
-    # @return [Array<Array, Integer, Integer>] upsized array, lhs, rhs
+    # @param arr    [Array]
+    #   the circular array.
+    # @param offset [Integer]
+    #   rotation amount.
+    #
+    # @return [Array<Array, Integer, Integer>]
+    #   upsized array, lhs, rhs.
     def upsize_circular_array(arr, offset)
       size = arr.size
-      arr = arr.rotate(offset)
-      arr.fill(nil, size, 2 * size)
+      arr = arr.rotate offset
+      arr.fill nil, size, 2 * size
       [arr, 0, size]
     end
 
-    # Convert a list of tokens to its wadler representation.
-    #
-    # @param tokens [Array[Token]]
-    # @param base_indent [Integer]
-    # @param printer_name [String]
-    #
     # @return [String]
-    def tokens_to_wadler(tokens, base_indent: 0, printer_name: 'out')
-      nb_spaces = base_indent
-      out = StringIO.new
+    def tokens_to_wadler(tokens, base_indent: 0, printer_name: 'out', width: tokens.length * 3)
+      printer = Oppen::Wadler.new(base_indent:, indent: 2, width:)
 
-      write = ->(txt) {
-        out << (' ' * nb_spaces) << txt << "\n"
-      }
-      display_break_token = ->(token) {
+      handle_break_token = ->(token) {
         if token.offset.positive?
-          write.("#{printer_name}.nest(#{token.offset}, \"\", \"\") {")
-          nb_spaces += 2
+          printer
+            .text("#{printer_name}.nest(indent: #{token.offset}) {")
+            .nest_open
+            .break
         end
 
-        case token
-        in Token::LineBreak
-          write.("#{printer_name}.break(line_continuation: #{token.line_continuation.inspect})")
-        in Token::Break
-          write.("#{printer_name}.breakable(#{token.str.inspect}, width: #{token.width}, " \
-                 "line_continuation: #{token.line_continuation.inspect})")
-        end
+        printer.text(
+          case token
+          in Token::LineBreak
+            "#{printer_name}.break(line_continuation: #{token.line_continuation.inspect})"
+          in Token::Break
+            "#{printer_name}.breakable(#{token.str.inspect}, width: #{token.width}, " \
+            "line_continuation: #{token.line_continuation.inspect})"
+          end,
+        )
 
-        if token.offset.positive?
-          nb_spaces -= 2
-          write.('}')
-        end
+        printer.nest_close.break.text '}' if token.offset.positive?
       }
 
-      tokens.each do |token|
+      tokens.each_with_index do |token, idx|
         case token
         in Token::String
-          write.("#{printer_name}.text(#{token.value.inspect}, width: #{token.width})")
+          printer.text "#{printer_name}.text(#{token.value.inspect}, width: #{token.width})"
         in Token::Break
-          display_break_token.(token)
+          handle_break_token.(token)
         in Token::Begin
-          write.("#{printer_name}.group(#{token.offset}, \"\", \"\", #{token.break_type_name}) {")
-          nb_spaces += 2
+          printer
+            .text("#{printer_name}.group(#{token.break_type.inspect}, indent: #{token.offset}) {")
+            .nest_open
         in Token::End
-          nb_spaces -= 2
-          write.('}')
+          printer.nest_close.break.text '}'
         in Token::EOF
-          write.('') # new line
+          nil
         end
+        printer.break if !tokens[idx + 1].is_a?(Token::End)
       end
-      out.string
+
+      printer.output
     end
   end
 end

data/lib/oppen/print_stack.rb

@@ -2,15 +2,16 @@
 
 # Oppen.
 module Oppen
-  # Class that represents a stack that builds an output string
-  # using the values of the tokens that were pushed into it.
+  # A stack of {Token}s.
   class PrintStack
-    # Class that represents an item in the print stack.
+    # An item in the print stack.
     class PrintStackEntry
-      # @return [Integer] Indentation level.
-      attr_reader :offset
-      # @return [Token::BreakType] (Called break in the original paper).
+      # @return [Token::BreakType]
+      #   Called `break` in the original paper.
       attr_reader :break_type
+      # @return [Integer]
+      #   Indentation level.
+      attr_reader :offset
 
       def initialize(offset, break_type)
         @offset = offset
@@ -18,34 +19,26 @@ module Oppen
       end
     end
 
-    # IO element that builds the output.
+    # IO sink for the output.
     attr_reader :buffer
-
-    # Config containing customization flags
+    # The printer's configuration, altering its behavior.
     attr_reader :config
-
-    # Callable that generate spaces
+    # Space generator, a callable.
     attr_reader :genspace
-
-    # Array representing the stack of PrintStackEntries.
+    # The stack of PrintStackEntries.
     attr_reader :items
-
-    # Delimiter between lines in output
+    # Delimiter between lines.
     attr_reader :new_line
-
-    # Maximum allowed width for printing (Called length in the original paper).
-    attr_reader :width
-
-    # Current available space (Called index in the original paper).
-    #
-    # @return [Integer] Current available space (Called index in the original paper).
+    # Current available space (`index` in the original paper).
     attr_reader :space
+    # Maximum allowed width for printing (`length` in the original paper).
+    attr_reader :width
 
     def initialize(width, new_line, config, space, out)
       @buffer = out
       @config = config
       @genspace =
-        if space.respond_to?(:call)
+        if space.respond_to? :call
           raise ArgumentError, 'space argument must be a Proc of arity 1' \
             if space.to_proc.arity != 1
 
@@ -53,28 +46,32 @@ module Oppen
         else
           ->(n) { space * n }
         end
-      @indent = 0
+      @indent = 0 # the amount of indentation to display on the next non empty new line.
       @items = []
       @new_line = new_line
       @width = width
       @space = width
     end
 
-    # Returns the output of the print stack
+    # The final pretty-printed output.
     #
     # @return [String]
+    #   The output of the print stack.
     def output
-      buffer.truncate(buffer.pos)
+      buffer.truncate buffer.pos
       buffer.string
     end
 
-    # Core method responsible for building the print stack and the output string.
+    # Core method responsible for building the print stack and the output
+    # string.
     #
-    # @note Called Print in the original paper.
+    # @note Called `Print` in the original paper.
     #
-    # @param token [Token]
-    # @param token_width [Integer]
-    # @param trim_on_break [Integer] Number of trailing whitespace characters to trim.
+    # @param token         [Token]
+    # @param token_width   [Integer]
+    # @param trim_on_break [Integer]
+    #   number of trailing whitespace characters to trim. If zero, no
+    #   character will be trimmed.
     #
     # @return [Nil]
     def print(token, token_width, trim_on_break: 0)
@@ -90,23 +87,21 @@ module Oppen
       end
     end
 
-    # Handle Begin Token.
+    # Handle {Token::Begin}.
     #
-    # @param token [Token]
+    # @param token       [Token]
     # @param token_width [Integer]
     #
     # @return [Nil]
-    #
-    # @see Token::Begin
     def handle_begin(token, token_width)
       if token_width > space
         type =
-          if token.break_type == Token::BreakType::CONSISTENT
-            Token::BreakType::CONSISTENT
+          if token.break_type == :consistent
+            :consistent
           else
-            Token::BreakType::INCONSISTENT
+            :inconsistent
           end
-        if config&.indent_anchor == Config::IndentAnchor::ON_BEGIN
+        if config&.indent_anchor == :current_offset
           indent = token.offset
           if !items.empty?
             indent += top.offset
@@ -116,55 +111,54 @@ module Oppen
         end
         push PrintStackEntry.new indent, type
       else
-        push PrintStackEntry.new 0, Token::BreakType::FITS
+        push PrintStackEntry.new 0, :fits
       end
     end
 
-    # Handle End Token.
+    # Handle {Token::End}.
     #
     # @return [Nil]
-    #
-    # @see Token::End
     def handle_end
       pop
     end
 
-    # Handle Break Token.
+    # Handle {Token::Break}.
     #
-    # @param token [Token]
-    # @param token_width [Integer]
-    # @param trim_on_break [Integer] Number of trailing whitespace characters to trim.
+    # @param token         [Token::Break]
+    # @param token_width   [Integer]
+    # @param trim_on_break [Integer]
+    #   number of trailing whitespace characters to trim.
+    #   0 = none.
     #
     # @return [Nil]
-    #
-    # @see Token::Break
     def handle_break(token, token_width, trim_on_break: 0)
       block = top
       case block.break_type
-      in Token::BreakType::FITS
+      in :fits
+        # No new line is needed (the block fits on the line).
         @space -= token.width
         write token
-      in Token::BreakType::CONSISTENT
+      in :consistent
         @space = block.offset - token.offset
         indent =
-          if config&.indent_anchor == Config::IndentAnchor::ON_BEGIN
+          if config&.indent_anchor == :current_offset
             token.offset
           else
             width - space
           end
-        erase(trim_on_break)
+        erase trim_on_break
         write token.line_continuation
         print_new_line indent
-      in Token::BreakType::INCONSISTENT
+      in :inconsistent
         if token_width > space
           @space = block.offset - token.offset
           indent =
-            if config&.indent_anchor == Config::IndentAnchor::ON_BEGIN
+            if config&.indent_anchor == :current_offset
               token.offset
             else
               width - space
             end
-          erase(trim_on_break)
+          erase trim_on_break
           write token.line_continuation
           print_new_line indent
         else
@@ -174,14 +168,12 @@ module Oppen
       end
     end
 
-    # Handle String Token.
+    # Handle {Token::String}.
     #
-    # @param token [Token]
+    # @param token       [Token::String]
     # @param token_width [Integer]
     #
     # @return [Nil]
-    #
-    # @see Token::String
     def handle_string(token, token_width)
       return if token.value.empty?
 
@@ -193,16 +185,16 @@ module Oppen
       write token
     end
 
-    # Push a PrintStackEntry into the stack.
+    # Push a {PrintStackEntry} into the stack.
     #
     # @param print_stack_entry [PrintStackEntry]
     #
     # @return [Nil]
     def push(print_stack_entry)
-      items.append(print_stack_entry)
+      items.append print_stack_entry
     end
 
-    # Pop a PrintStackEntry from the stack.
+    # Pop a {PrintStackEntry} from the stack.
     #
     # @return [PrintStackEntry]
     def pop
@@ -226,14 +218,15 @@ module Oppen
 
     # Add a new line to the output.
     #
-    # @note Called PrintNewLine as well in the original paper.
+    # @note Called `PrintNewLine` as well in the original paper.
     #
-    # @param amount [Integer] indentation amount.
+    # @param amount [Integer]
+    #   indentation amount.
     #
     # @return [Nil]
     def print_new_line(amount)
       write new_line
-      if config&.indent_anchor == Config::IndentAnchor::ON_BEGIN
+      if config&.indent_anchor == :current_offset
         @space = width - top.offset - amount
         @indent = width - space
       else
@@ -247,7 +240,7 @@ module Oppen
     #
     # @return [Nil]
     def write(obj)
-      buffer.write(obj.to_s)
+      buffer.write obj.to_s
     end
 
     # Erase the last `count` characters.
@@ -264,7 +257,7 @@ module Oppen
 
     # Add indentation by `amount`.
     #
-    # @note Called Indent as well in the original paper.
+    # @note Called `Indent` as well in the original paper.
     #
     # @param amount [Integer]
     #