oppen 0.9.7 → 0.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b656616fe07cf5b29b8dfa43f0b72ed6dbf80c56a9ca6790745a8db27f058ed7
-  data.tar.gz: 3d46ddc3a703d029ac22460ac504cf2928f95d804d32e0266f0de7ffbbfd3359
+  metadata.gz: '008545ae6d86a7415e434ef51a19872fbf5b768db232d70bbac025667e002604'
+  data.tar.gz: a989a6e8d422c363e7ebca36fc10dac4ad030f145afc2b4bc152c9cff5bdfe49
 SHA512:
-  metadata.gz: 7b69f0365a507dc9fca546cbfea064593a48d0d85140cd894ed2ff256e13c4c0e772bf9e0d2b29f9eefd9121c8b3adf03da93137c15b3c9570f6a7e49ed435b2
-  data.tar.gz: aa608fa2238dc8eea6bf3ce5d03f10e6f8059eda98c02d1e53fa06f9ac9301b03b42e54b38ed4f945c28766c4959b441cc190b76f0f176a72c7f52967096258a
+  metadata.gz: 9a3e32d3a05c638bd26a9e170d737186c9635eeb3c54844869b108c8252fdafa942a05a76a1e3d3d25d5e93a47d076c280f7346c1c313b5c7159a8f3d1166ef6
+  data.tar.gz: 1f3c076ea8b298f5a772d9c209c4bc64087f6093576e41e2ffb6289b5d0aba08c1b3ed9d3022ebb14b7d7fe4c083804e60219735bce5c00f96785e9dede2bb69

data/README.md

@@ -31,8 +31,7 @@ monkeypatching.
 
 ## Usage
 
-> [!WARNING]
-> Lands when the APIs are stable.
+A few examples of the API usage can be found in [examples/](examples/README.md).
 
 ## Oppen vs Wadler
 

data/lib/oppen/mixins.rb

@@ -4,70 +4,73 @@ 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(width: width)
+      printer.base_indent(base_indent)
+      indent = 2
 
-      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(#{token.offset}, '', '') {"
+          printer.nest_open indent
+          printer.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.('}')
+          printer.nest_close indent
+          printer.break
+          printer.text '}'
         end
       }
 
-      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.offset}, '', '', #{token.break_type.inspect}) {"
+          printer.nest_open indent
         in Token::End
-          nb_spaces -= 2
-          write.('}')
+          printer.nest_close indent
+          printer.break
+          printer.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)
@@ -84,29 +81,27 @@ module Oppen
       in Token::End
         handle_end
       in Token::Break
-        handle_break token, token_width, trim_on_break:
+        handle_break token, token_width, trim_on_break: trim_on_break
       in Token::String
         handle_string token, token_width
       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]
     #