oppen 0.9.6 → 0.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 209072194fbb082bd25f2583b7f930e38c79ca042c21e711e18dd7295ee00e86
-  data.tar.gz: 6eeb620d7d3bd6599477a46a2a5b9df86db2bc8c6a0f07a619d065245393127f
+  metadata.gz: '008545ae6d86a7415e434ef51a19872fbf5b768db232d70bbac025667e002604'
+  data.tar.gz: a989a6e8d422c363e7ebca36fc10dac4ad030f145afc2b4bc152c9cff5bdfe49
 SHA512:
-  metadata.gz: a2f8d7bd7b199b7ef0d5a97feebbe456fea9e557f6535760ad84b21a304d73c52ea954f392e7c07e0b682844fe86c0c8ccc4ef6786057785cba9f02f58c31c14
-  data.tar.gz: 31a73892d3afff56d85c60a6756d6fedbd2bce259d7ca259b662a7f7002549fcb53146f2fb1a32136ae2c8cca03b20ded90d95a814363d18d0d80192db79c39b
+  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,50 +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]
-    #
     # @return [String]
-    def tokens_to_wadler(tokens, base_indent = 4)
-      out = StringIO.new
-      write = ->(txt, nb_spaces) {
-        out.write("#{' ' * nb_spaces}#{txt}\n")
+    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
+
+      handle_break_token = ->(token) {
+        if token.offset.positive?
+          printer.text "#{printer_name}.nest(#{token.offset}, '', '') {"
+          printer.nest_open indent
+          printer.break
+        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?
+          printer.nest_close indent
+          printer.break
+          printer.text '}'
+        end
       }
-      nb_spaces = base_indent
-      tokens.each do |token|
+
+      tokens.each_with_index do |token, idx|
         case token
         in Token::String
-          write.call("out.text '#{token}'", nb_spaces)
-        in Token::LineBreak
-          write.call('out.break', nb_spaces)
+          printer.text "#{printer_name}.text(#{token.value.inspect}, width: #{token.width})"
         in Token::Break
-          write.call('out.breakable', nb_spaces)
+          handle_break_token.(token)
         in Token::Begin
-          write.call('out.group {', nb_spaces)
-          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.call('}', nb_spaces)
+          printer.nest_close indent
+          printer.break
+          printer.text '}'
         in Token::EOF
-          write.call('', nb_spaces) # 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,58 +46,62 @@ 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.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 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)
+    def print(token, token_width, trim_on_break: 0)
       case token
       in Token::Begin
         handle_begin token, token_width
       in Token::End
         handle_end
       in Token::Break
-        handle_break token, token_width
+        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
@@ -114,52 +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 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)
+    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
         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
           write token.line_continuation
           print_new_line indent
         else
@@ -169,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?
 
@@ -188,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
@@ -221,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
@@ -242,12 +240,24 @@ module Oppen
     #
     # @return [Nil]
     def write(obj)
-      buffer.write(obj.to_s)
+      buffer.write obj.to_s
+    end
+
+    # Erase the last `count` characters.
+    #
+    # @param count [Integer]
+    #
+    # @return [Nil]
+    def erase(count = 0)
+      raise ArgumentError, "count = #{count} must be non-negative" if count.negative?
+
+      buffer.seek(-count, IO::SEEK_CUR)
+      @space += count
     end
 
     # 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]
     #
@@ -255,7 +265,7 @@ module Oppen
     def indent(amount)
       raise ArgumentError 'Indenting using negative amount' if amount.negative?
 
-      write genspace.call(amount) if amount.positive?
+      write genspace.(amount) if amount.positive?
     end
   end
 end