oppen 0.9.7 → 0.9.8

data/lib/wadler/print.rb

@@ -4,30 +4,49 @@
 module Oppen
   # Wadler.
   class Wadler
+    # @return [Config]
+    #   The printer's configuration, altering its behavior.
     attr_reader :config
+    # @return [Integer]
+    #   the current indentation amount.
     attr_reader :current_indent
-    attr_reader :space
+    # @return [String]
+    #   the new line string, e.g. `\n`.
     attr_reader :new_line
+    # @return [Object]
+    #   the output string buffer. It should have a `write` and `string` methods.
     attr_reader :out
+    # @return [Proc]
+    #   space generator, a callable.
+    attr_reader :space
+    # @return [Array<Token>]
+    #   the tokens list that is being built.
     attr_reader :tokens
+    # @return [String]
+    #   the whitespace character. Used to trim trailing whitespaces.
     attr_reader :whitespace
+    # @return [Integer]
+    #   maximum line width.
     attr_reader :width
 
-    # @param config [Oppen::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 new_line [String]
-    # @param out [Object] should have a write and string method
-    # @param width [Integer]
-    # @param whitespace [String] the whitespace character. Used to trim trailing whitespaces.
+    # @param config     [Config]
+    #   to customize the printer's behavior.
+    # @param new_line   [String]
+    #   the new line String.
+    # @param out        [Object]
+    #   the output string buffer. It should have a `write` and `string` methods.
+    # @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 whitespace [String]       the whitespace character. Used to trim trailing whitespaces.
+    # @param width      [Integer]      maximum line width desired.
+    #
     # @see Token::Whitespace
-    def initialize(config: Config.wadler, space: ' ',
-                   new_line: "\n", out: StringIO.new,
-                   width: 80, whitespace: ' ')
+    def initialize(config: Config.wadler, new_line: "\n",
+                   out: StringIO.new, space: ' ',
+                   whitespace: ' ', width: 80)
       @config = config
       @current_indent = 0
       @space = space
@@ -38,7 +57,8 @@ module Oppen
       @whitespace = whitespace
     end
 
-    # Add missing Begin, End or EOF tokens.
+    # Add missing {Token::Begin}, {Token::End} or {Token::EOF}.
+    #
     # @return [Nil]
     def add_missing_begin_and_end
       if !tokens.first.is_a? Token::Begin
@@ -48,42 +68,124 @@ module Oppen
       tokens << Oppen.eof if !tokens.last.is_a?(Oppen::Token::EOF)
     end
 
-    # Generate the output string of the built list of tokens
-    # using Oppen's pretty printing algorithm.
+    # Call this to extract the final pretty-printed output.
     #
     # @return [String]
     def output
       add_missing_begin_and_end
-      Oppen.print(tokens:, new_line:, config:, space:, out:, width:)
+      Oppen.print(
+        tokens: tokens,
+        new_line: new_line,
+        config: config,
+        space: space,
+        out: out,
+        width: width,
+      )
     end
 
-    # Generate the the list of Wadler commands needed to build the built
-    # list of tokens.
+    # Convert a list of tokens to its wadler representation.
+    #
+    # This method reverse engineers a tokens list to transform it into Wadler
+    # printing commands. It can be particularly useful when debugging a black
+    # box program.
+    #
+    # @option kwargs [Integer] :base_indent
+    #   the base indentation amount of the output.
+    # @option kwargs [String]  :printer_name
+    #   the name of the Wadler instance in the output.
+    #
+    # @example
+    #   out = Oppen::Wadler.new
+    #   out.group {
+    #     out.text('Hello World!')
+    #   }
+    #   out.show_print_commands(out_name: 'out')
+    #
+    #   # =>
+    #   # out.group(0, "", "", :consistent) {
+    #   #   out.text("Hello World!", width: 12)
+    #   # }
     #
     # @return [String]
-    def show_print_commands(**)
+    def show_print_commands(**kwargs)
       add_missing_begin_and_end
-      Oppen.tokens_to_wadler(tokens, **)
+      Oppen.tokens_to_wadler(tokens, **kwargs)
     end
 
-    # @param indent [Integer] group indentation
-    # @param open_obj [String] group opening delimiter
-    # @param close_obj [String] group closing delimiter
-    # @param break_type [Oppen::Token::BreakType] group breaking type
+    # Create a new group.
+    #
+    # @param indent     [Integer]
+    #   indentation.
+    # @param open_obj   [String]
+    #   opening delimiter.
+    # @param close_obj  [String]
+    #   closing delimiter.
+    # @param break_type [Token::BreakType]
+    #   break type.
+    #
+    # @yield
+    #   the block of text in a group.
+    #
+    # @example
+    #   out = Oppen::Wadler.new
+    #   out.text 'a'
+    #   out.group(2, '{', '}') {
+    #     out.break
+    #     out.text 'b'
+    #   }
+    #   out.output
+    #
+    #   # =>
+    #   # a
+    #   #   {
+    #   #   b
+    #   #   }
+    #
+    # @example Consistent Breaking
+    #   out = Oppen::Wadler.new
+    #   out.group(0, '', '', :consistent) {
+    #     out.text 'a'
+    #     out.break
+    #     out.text 'b'
+    #     out.breakable
+    #     out.text 'c'
+    #   }
+    #   out.output
+    #
+    #   # =>
+    #   # a
+    #   # b
+    #   # c
+    #
+    # @example Inconsistent Breaking
+    #   out = Oppen::Wadler.new
+    #   out.group(0, '', '', :inconsistent) {
+    #     out.text 'a'
+    #     out.break
+    #     out.text 'b'
+    #     out.breakable
+    #     out.text 'c'
+    #   }
+    #   out.output
     #
-    # @yield the block of text in a group
+    #   # =>
+    #   # a
+    #   # b c
     #
     # @return [Nil]
+    #
+    # @see Oppen.begin_consistent
+    # @see Oppen.begin_inconsistent
     def group(indent = 0, open_obj = '', close_obj = '',
-              break_type = Oppen::Token::BreakType::CONSISTENT)
+              break_type = :consistent)
       raise ArgumentError, "#{open_obj.nil? ? 'open_obj' : 'close_obj'} cannot be nil" \
         if open_obj.nil? || close_obj.nil?
 
       tokens <<
         case break_type
-        in Oppen::Token::BreakType::CONSISTENT
+        in :consistent
           Oppen.begin_consistent(offset: indent)
-        in Oppen::Token::BreakType::INCONSISTENT
+        in :inconsistent
           Oppen.begin_inconsistent(offset: indent)
         end
 
@@ -102,9 +204,44 @@ module Oppen
       tokens << Oppen.end
     end
 
-    # @param indent [Integer] nest indentation
-    # @param open_obj [String] nest opening delimiter
-    # @param close_obj [String] nest closing delimiter
+    # Create a new non-strict {group}.
+    #
+    # {group}s isolate breaking decisions, and in that sense they're considered
+    # strict; e.g. when a breakable is transformed into an actual break, its
+    # parent {group} might not get broken if the result could fit on the line.
+    #
+    # This is not the case with {nest}: if the same breakable was in a {nest}, the
+    # {group} containing the {nest} will also be broken.
+    #
+    # @note indentation cannot happen if there are no breaks in the {nest}.
+    #
+    # @note a {nest} will not forcibly indent its content if the break type of
+    # the enclosing {group} is `:inconsistent`.
+    #
+    # @param indent    [Integer]
+    #   indentation.
+    # @param open_obj  [String]
+    #   opening delimiter. A {break} is implicitly slipped after it if it's not empty.
+    # @param close_obj [String]
+    #   closing delimiter. A {break} is implicitly slipped before it if it's not empty.
+    #
+    # @yield
+    #   the block of text in a nest.
+    #
+    # @example
+    #   out = Oppen::Wadler.new
+    #   out.nest(2, '{', '}') {
+    #     out.text 'a'
+    #     out.break
+    #     out.text 'b'
+    #   }
+    #   out.output
+    #
+    #   # =>
+    #   # {
+    #   #   a
+    #   #   b
+    #   # }
     #
     # @return [Nil]
     def nest(indent, open_obj = '', close_obj = '')
@@ -130,7 +267,10 @@ module Oppen
       text(close_obj)
     end
 
+    # Create a new text element.
+    #
     # @param value [String]
+    #   the value of the token.
     #
     # @return [Nil]
     def text(value, width: value.length)
@@ -142,30 +282,56 @@ module Oppen
         end
         tokens << Oppen.whitespace(match)
       else
-        tokens << Oppen.string(value, width:)
+        tokens << Oppen.string(value, width: width)
       end
     end
 
-    # @param str [String]
-    # @param line_continuation [String] If a new line is needed display this string before the new line
+    # Create a new breakable element.
+    #
+    # @param str               [String]
+    #   the value of the token that will be displayed if no new line is needed.
+    # @param line_continuation [String]
+    #   printed before the line break.
+    # @param width             [Integer]
+    #   the width of the token.
     #
     # @return [Nil]
-    def breakable(str = ' ', width: str.length, line_continuation: '')
-      tokens << Oppen.break(str, width:, line_continuation:, offset: current_indent)
+    #
+    # @see Wadler#break example on `line_continuation`.
+    def breakable(str = ' ', line_continuation: '', width: str.length)
+      tokens << Oppen.break(str, width: width, line_continuation: line_continuation, offset: current_indent)
     end
 
-    # @param line_continuation [String] If a new line is needed display this string before the new line
+    # Create a new break element.
+    #
+    # @param line_continuation [String]
+    #   printed before the line break.
+    #
+    # @example
+    #   out = Oppen::Wadler.new
+    #   out.text 'a'
+    #   out.break
+    #   out.text 'b'
+    #   out.break line_continuation: '#'
+    #   out.text 'c'
+    #   out.output
+    #
+    #   # =>
+    #   # a
+    #   # b#
+    #   # c
     #
     # @return [Nil]
     def break(line_continuation: '')
-      tokens << Oppen.line_break(line_continuation:, offset: current_indent)
+      tokens << Oppen.line_break(line_continuation: line_continuation, offset: current_indent)
     end
 
     # @!group Helpers
 
-    # Set a base indenetaion level to the printer.
+    # Set a base indenetaion level for the printer.
     #
     # @param indent [Integer]
+    #   the amount of indentation.
     #
     # @return [Nil]
     def base_indent(indent = 0)
@@ -175,9 +341,14 @@ module Oppen
     # Open a consistent group.
     #
     # @param inconsistent [Boolean]
+    #   whether the break type of the group should be inconsistent.
     # @param indent       [Integer]
+    #   the amount of indentation of the group.
     #
     # @return [Nil]
+    #
+    # @see Oppen.begin_consistent
+    # @see Oppen.begin_inconsistent
     def group_open(inconsistent: false, indent: 0)
       tokens <<
         if inconsistent
@@ -194,9 +365,10 @@ module Oppen
       tokens << Oppen.end
     end
 
-    # Open a consistent group with indent.
+    # Open a consistent group and add indent amount.
     #
     # @param indent [Integer]
+    #   the amount of indentation of the group.
     #
     # @return [Nil]
     def indent_open(indent)
@@ -204,9 +376,10 @@ module Oppen
       group_open
     end
 
-    # Close a group with indent.
+    # Close a group and subtract indent.
     #
     # @param indent [Integer]
+    #   the amount of indentation of the group.
     #
     # @return [Nil]
     def indent_close(group, indent)
@@ -214,18 +387,20 @@ module Oppen
       group_close(group)
     end
 
-    # Open a nest by indent.
+    # Open a nest by adding indent.
     #
     # @param indent [Integer]
+    #   the amount of indentation of the nest.
     #
     # @return [Nil]
     def nest_open(indent)
       @current_indent += indent
     end
 
-    # Close a nest by indent.
+    # Close a nest by subtracting indent.
     #
     # @param indent [Integer]
+    #   the amount of indentation of the nest.
     #
     # @return [Nil]
     def nest_close(indent)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oppen
 version: !ruby/object:Gem::Version
-  version: 0.9.7
+  version: 0.9.8
 platform: ruby
 authors:
 - Amine Mike El Maalouf <amine.el-maalouf@epita.fr>
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-12-05 00:00:00.000000000 Z
+date: 2024-12-30 00:00:00.000000000 Z
 dependencies: []
 description: Implementation of the Oppen's pretty printing algorithm
 email: 
@@ -37,9 +37,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="