oppen 0.9.7 → 1.0.0

data/lib/oppen/printer.rb

@@ -2,9 +2,9 @@
 
 require 'stringio'
 
-require_relative 'scan_stack'
-require_relative 'print_stack'
 require_relative 'mixins'
+require_relative 'print_stack'
+require_relative 'scan_stack'
 
 # Oppen.
 module Oppen
@@ -12,73 +12,82 @@ module Oppen
   class Printer
     extend Mixins
 
+    # The printer's configuration, altering its behavior.
+    #
+    # @return [Config]
     attr_reader :config
-    # Ring buffer left index.
+    # Ring buffer's left index.
     #
-    # @note Called left as well in the original paper.
+    # @note Called `left` as well in the original paper.
+    #
+    # @return [Integer]
     attr_reader :left
-
-    # Total number of spaces needed to print from start of buffer to the left.
+    # Number of spaces needed to print from start of buffer to left.
     #
-    # @note Called leftTotal as well in the original paper.
+    # @note Called `leftTotal` as well in the original paper.
+    #
+    # @return [Integer]
     attr_reader :left_total
-
-    # @note Called printStack as well in the original paper.
+    # A stack of {Token}s; builds the the final output.
+    #
+    # @note Called `printStack` as well in the original paper.
+    #
+    # @return [PrintStack]
     attr_reader :print_stack
-
-    # Ring buffer right index.
+    # Ring buffer's right index.
     #
-    # @note Called right as well in the original paper.
+    # @note Called `right` as well in the original paper.
+    #
+    # @return [Integer]
     attr_reader :right
-
-    # Total number of spaces needed to print from start of buffer to the right.
+    # Number of spaces needed to print from start of buffer to right.
     #
-    # @note Called leftTotal as well in the original paper.
+    # @note Called `leftTotal` as well in the original paper.
+    #
+    # @return [Integer]
     attr_reader :right_total
-
     # Potential breaking positions.
     #
-    # @note Called scanStack as well in the original paper.
+    # @note Called `scanStack` as well in the original paper.
+    #
+    # @return [ScanStack]
     attr_reader :scan_stack
-
     # Size buffer, initially filled with nil.
     #
-    # @note Called size as well in the original paper.
+    # @note Called `size` as well in the original paper.
+    #
+    # @return [Integer]
     attr_reader :size
-
     # Token buffer, initially filled with nil.
     #
-    # @note Called token in the original paper.
+    # @note Called `token` in the original paper.
+    #
+    # @return [Array<Tokens>]
     attr_reader :tokens
 
-    # Some description
-    #
-    # @example
-    #   "This is a string" # => and this is a comment
-    #   out = Oppen::Wadler.new (margin: 13) # Hawn
-    #   # Baliz
-    #
-    # @example
-    #   "This is a string" # => and this is a comment
-    #   # var = 12
-    #
-    # @param width [Integer] maximum line width desired.
-    # @param new_line [String]  the delimiter between lines.
-    # @param config [Config]
-    # @param space [String, Proc] could be a String or a callable.
-    #   If it's a string, spaces will be generated with the the
-    #   lambda `->(n){ n * space }`, where `n` is the number of columns
-    #   to indent.
-    #   If it's a callable, it will receive `n` and it needs to return
-    #   a string.
-    # @param out [Object] should have a write and string method
+    # @note Called `PrettyPrintInit` in the original paper.
+    #
+    # @param config   [Config]
+    #   to customize the printer's behavior.
+    # @param new_line [String]
+    #   the delimiter between lines.
+    # @param space    [String, Proc]
+    #   indentation string or a string generator.
+    #   - If a `String`, spaces will be generated with the the lambda
+    #     `->(n){ space * n }`, where `n` is the number of columns to indent.
+    #   - If a `Proc`, it will receive `n` and it needs to return a `String`.
+    # @param width    [Integer]
+    #   maximum line width desired.
+    # @param out      [Object]
+    #   the output string buffer. It should have both `write` and `string`
+    #   methods.
     def initialize(width, new_line, config = Config.oppen,
                    space = ' ', out = StringIO.new)
       # Maximum size if the stacks
       n = 3 * width
 
       @config = config
-      @last_whitespaces_width = 0
+      @last_whitespaces_width = 0 # Accumulates the width of the last Whitespace tokens encountered.
       @left = 0
       @left_total = 1
       @print_stack = PrintStack.new width, new_line, config, space, out
@@ -89,14 +98,16 @@ module Oppen
       @tokens = Array.new n
     end
 
+    # The final pretty-printed output.
+    #
     # @return [String]
-    def output
-      print_stack.output
-    end
+    #   the output of the print stack.
+    def output = print_stack.output
 
-    # Core function of the algorithm responsible for populating the scan and print stack.
+    # Core function of the algorithm responsible for populating the {ScanStack}
+    # and {PrintStack}.
     #
-    # @note Called PrettyPrint as well in the original paper.
+    # @note Called `PrettyPrint` as well in the original paper.
     #
     # @param token [Token]
     #
@@ -120,11 +131,9 @@ module Oppen
       end
     end
 
-    # Handle EOF Token.
+    # Handle {Token::EOF}.
     #
     # @return [Nil]
-    #
-    # @see Token::EOF
     def handle_eof
       if !scan_stack.empty?
         check_stack 0
@@ -133,11 +142,11 @@ module Oppen
       print_stack.indent 0
     end
 
-    # Handle Begin Token.
+    # Handle {Token::Begin}.
     #
-    # @return [Nil]
+    # @param token [Token::Begin]
     #
-    # @see Token::Begin
+    # @return [Nil]
     def handle_begin(token)
       if scan_stack.empty?
         @left = 0
@@ -145,7 +154,7 @@ module Oppen
         @right = 0
         @right_total = 1
 
-        # config.trim_trailing_whitespaces
+        # config.trim_trailing_whitespaces.
         @tokens[-1] = nil
       else
         advance_right
@@ -155,11 +164,11 @@ module Oppen
       scan_stack.push right
     end
 
-    # Handle End Token.
+    # Handle {Token::End}.
     #
-    # @return [Nil]
+    # @param token [Token::End]
     #
-    # @see Token::End
+    # @return [Nil]
     def handle_end(token)
       if scan_stack.empty?
         print_stack.print token, 0
@@ -176,11 +185,11 @@ module Oppen
       end
     end
 
-    # Handle Break Token.
+    # Handle {Token::Break}.
     #
-    # @return [Nil]
+    # @param token [Token::Break]
     #
-    # @see Token::Break
+    # @return [Nil]
     def handle_break(token)
       if scan_stack.empty?
         @left = 0
@@ -188,7 +197,7 @@ module Oppen
         @right = 0
         @right_total = 1
 
-        # config.trim_trailing_whitespaces
+        # config.trim_trailing_whitespaces.
         tokens[-1] = nil
         print_stack.erase @last_whitespaces_width
         @last_whitespaces_width = 0
@@ -202,11 +211,11 @@ module Oppen
       @right_total += token.width
     end
 
-    # Handle String Token.
+    # Handle {Token::String}.
     #
-    # @return [Nil]
+    # @param token [Token::String]
     #
-    # @see Token::String
+    # @return [Nil]
     def handle_string(token)
       if scan_stack.empty?
         print_stack.print token, token.width
@@ -221,7 +230,7 @@ module Oppen
 
     # Flushes the input if possible.
     #
-    # @note Called CheckStream as well in the original paper.
+    # @note Called `CheckStream` as well in the original paper.
     #
     # @return [Nil]
     def check_stream
@@ -236,9 +245,9 @@ module Oppen
       check_stream
     end
 
-    # Advances the `right` pointer.
+    # Advances the {#right} pointer.
     #
-    # @note Called AdvanceRight as well in the original paper.
+    # @note Called `AdvanceRight` as well in the original paper.
     #
     # @return [Nil]
     def advance_right
@@ -253,10 +262,13 @@ module Oppen
       @tokens, @left, @right = ScanStack.upsize_circular_array(@tokens, @left)
     end
 
-    # Advances the `left` pointer and lets the print stack
-    # print some of the tokens it contains.
+    # Advances the {#left} pointer and lets the print stack print some of the
+    # tokens it contains.
+    #
+    # @note Called `AdvanceLeft` as well in the original paper.
     #
-    # @note Called AdvanceLeft as well in the original paper.
+    # @param token       [Token]
+    # @param token_width [Integer]
     #
     # @return [Nil]
     def advance_left(token, token_width)
@@ -296,12 +308,13 @@ module Oppen
       advance_left tokens[left], size[left]
     end
 
-    # Updates the size buffer taking into
-    # account the length of the current group.
+    # Updates the {#size} buffer taking into account the length of the current
+    # group.
     #
-    # @note Called CheckStack as well in the original paper.
+    # @note Called `CheckStack` as well in the original paper.
     #
-    # @param depth [Integer] depth of the group
+    # @param depth [Integer]
+    #   depth of the group.
     #
     # @return [Nil]
     def check_stack(depth)
@@ -309,12 +322,12 @@ module Oppen
 
       x = scan_stack.top
       case tokens[x]
-      when Token::Begin
+      in Token::Begin
         if depth.positive?
           size[scan_stack.pop] = size[x] + right_total
           check_stack depth - 1
         end
-      when Token::End
+      in Token::End
         size[scan_stack.pop] = 1
         check_stack depth + 1
       else

data/lib/oppen/scan_stack.rb

@@ -9,23 +9,28 @@ module Oppen
     extend Mixins
 
     def initialize(size, config)
-      @bottom = 0
-      @config = config
-      @empty = true
-      @stack = Array.new(size)
-      @top = 0
+      @bottom = 0             # Points to the bottom of the stack.
+      @config = config        # Printing config.
+      @empty = true           # Emptiness flag.
+      @stack = Array.new size # The fixed sized stack.
+      @top = 0                # Points to the top of the stack.
     end
 
+    # Whether the stack is empty.
+    #
     # @return [Boolean]
-    def empty?
-      @empty
-    end
+    def empty? = @empty
 
+    # The current length of the stack.
+    #
     # @return [Integer]
-    def length
-      @stack.length
-    end
+    def length = @stack.length
 
+    # The top element of the stack.
+    #
+    # @raise [RuntimeError]
+    #   when accessing empty stack.
+    #
     # @return [Object]
     def top
       if empty?
@@ -35,6 +40,11 @@ module Oppen
       @stack[@top]
     end
 
+    # The bottom element of the stack.
+    #
+    # @raise [RuntimeError]
+    #   when accessing empty stack.
+    #
     # @return [Object]
     def bottom
       if empty?
@@ -66,16 +76,20 @@ module Oppen
     #
     # @param value [Object]
     #
+    # @raise [RuntimeError]
+    #   when the stack is full and the `upsize_stack` flag is not activated in
+    #   {Config}.
+    #
     # @return [Nil]
     def push(value)
       if empty?
         @empty = false
       else
-        @top = increment(@top)
+        @top = increment @top
         if @top == @bottom
           raise 'Stack full' if !@config.upsize_stack?
 
-          @stack, @bottom, @top = ScanStack.upsize_circular_array(@stack, @bottom)
+          @stack, @bottom, @top = ScanStack.upsize_circular_array @stack, @bottom
         end
       end
       @stack[@top] = value
@@ -83,6 +97,9 @@ module Oppen
 
     # Pop a value from the top.
     #
+    # @raise [RuntimeError]
+    #   when accessing empty stack.
+    #
     # @return [Nil]
     def pop
       if empty?
@@ -93,13 +110,16 @@ module Oppen
       if @top == @bottom
         @empty = true
       else
-        @top = decrement(@top)
+        @top = decrement @top
       end
       res
     end
 
     # Pop a value from the bottom.
     #
+    # @raise [RuntimeError]
+    #   when accessing empty stack.
+    #
     # @return [Nil]
     def pop_bottom
       if empty?
@@ -110,7 +130,7 @@ module Oppen
       if @top == @bottom
         @empty = true
       else
-        @bottom = increment(@bottom)
+        @bottom = increment @bottom
       end
       res
     end
@@ -119,7 +139,7 @@ module Oppen
     #
     # @param offset [Integer]
     #
-    # @return [Array[Integer]]
+    # @return [Array<Integer>]
     def update_indexes(offset)
       @stack = @stack.map { |val|
         (val + offset) % length if val

data/lib/oppen/token.rb

@@ -4,27 +4,14 @@
 module Oppen
   # Token.
   class Token
-    # BreakType.
+    # Default token width.
     #
-    # FITS => No break is needed (the block fits on the line).
-    # INCONSISTENT => New line will be forced only if necessary.
-    # CONSISTENT => Each subblock of the block will be placed on a new line.
-    module BreakType
-      # @return [Integer]
-      FITS = 0
-      # @return [Integer]
-      INCONSISTENT = 1
-      # @return [Integer]
-      CONSISTENT = 2
-    end
-
-    # Default token width
     # @return [Integer]
     def width = 0
 
     # String Token.
     class String < Token
-      # @return [String] String value.
+      # @return [String]
       attr_reader :value
       # @return [Integer]
       attr_reader :width
@@ -39,15 +26,21 @@ module Oppen
       def to_s = value
     end
 
-    # If a [Token::Break] follows [Token::Whitespace], and an actual break
-    # is issued, and `trim_trailing_whitespaces == true`, then all whitespace
-    # text will be omitted from the output.
+    # This token is not part of Oppen's original work. We introduced it to
+    # handle trailing whitespaces.
+    #
+    # When the config flag `trim_trailing_whitespaces == true`, and a new line
+    # is needed, all the {Token::Whitespace} figuring after the last {Token::String}
+    # will be be skipped.
     class Whitespace < ::Oppen::Token::String
     end
 
     # Break Token.
     class Break < Token
-      # @return [String] If a new line is needed display this string before the new line
+      # @return [String]
+      #   If a new line is needed, display this string before the new line.
+      #
+      # @see Wadler#break example on `line_continuation`.
       attr_reader :line_continuation
       # @return [Integer] Indentation.
       attr_reader :offset
@@ -56,7 +49,7 @@ module Oppen
       # @return [Integer]
       attr_reader :width
 
-      def initialize(str = ' ', width: str.length, line_continuation: '', offset: 0)
+      def initialize(str = ' ', line_continuation: '', offset: 0, width: str.length)
         raise ArgumentError, 'line_continuation cannot be nil' if line_continuation.nil?
 
         @line_continuation = line_continuation
@@ -66,6 +59,8 @@ module Oppen
         super()
       end
 
+      # Convert token to String.
+      #
       # @return [String]
       def to_s = str
     end
@@ -87,33 +82,53 @@ module Oppen
     class Begin < Token
       # @return [BreakType]
       attr_reader :break_type
-      # @return [Integer] Indentation.
+      # @return [Integer]
       attr_reader :offset
 
-      def initialize(break_type: BreakType::INCONSISTENT, offset: 2)
+      def initialize(break_type: :inconsistent, offset: 2)
         @offset = offset
         @break_type = break_type
         super()
       end
-
-      # The break_type name as a String.
-      #
-      # @return [String]
-      def break_type_name
-        case @break_type
-        in BreakType::FITS         then 'Oppen::Token::BreakType::FITS'
-        in BreakType::INCONSISTENT then 'Oppen::Token::BreakType::INCONSISTENT'
-        in BreakType::CONSISTENT   then 'Oppen::Token::BreakType::CONSISTENT'
-        end
-      end
     end
 
-    # End Token
+    # End Token.
     class End < Token
       nil
     end
 
-    # EOF Token
+    # The EOF token can be interpreted as an output flush operation.
+    #
+    # @note Multiple {Token::EOF} tokens can be present in the same list of tokens.
+    #
+    # @example
+    #   tokens = [
+    #     Oppen::Token::Begin.new,
+    #     Oppen::Token::String.new('XXXXXXXXXX'),
+    #     Oppen::Token::End.new,
+    #     Oppen::Token::EOF.new,
+    #     Oppen::Token::Begin.new,
+    #     Oppen::Token::String.new('YYYYYYYYYY'),
+    #     Oppen::Token::End.new,
+    #   ]
+    #   Oppen.print tokens:
+    #
+    #   # =>
+    #   # XXXXXXXXXX
+    #
+    #   tokens = [
+    #     Oppen::Token::Begin.new,
+    #     Oppen::Token::String.new('XXXXXXXXXX'),
+    #     Oppen::Token::End.new,
+    #     Oppen::Token::Begin.new,
+    #     Oppen::Token::String.new('YYYYYYYYYY'),
+    #     Oppen::Token::End.new,
+    #     Oppen::Token::EOF.new,
+    #   ]
+    #   Oppen.print tokens:
+    #
+    #   # =>
+    #   # XXXXXXXXXXYYYYYYYYYY
     class EOF < Token
       nil
     end

data/lib/oppen/version.rb

@@ -4,6 +4,7 @@
 module Oppen
   # Oppen version
   #
-  # @return [String] current version
-  VERSION = '0.9.7' # managed by release.sh
+  # @return [String]
+  #   current version
+  VERSION = '1.0.0' # managed by release.sh
 end