Deviate from ruby/pretty_print and enrich the API

.github/workflows/test.yml

@@ -37,6 +37,8 @@ jobs:
         run: just lint
       - name: test
         run: just test
+      - name: examples
+        run: just examples
       - name: doc
         run: just doc
       - name: package gem

.rubocop.yml

@@ -79,6 +79,9 @@ Style/Lambda:
 Style/LambdaCall:
   EnforcedStyle: braces
 
+Style/MultilineBlockChain:
+  Enabled: false
+
 Style/TrailingCommaInArrayLiteral:
   EnforcedStyleForMultiline: comma
 

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [unreleased]
 
+- Deprarture from the `ruby/pretty_print` API with Wadler:
+  - accept `indent` which will apply to `nest` and `group` implicitly if no
+    `indent:` kwarg is passed.
+  - accept `base_indent` which sets the base global indentation level for
+    the whole printer.
+  - all printing methods return `self` for call chaining.
+- Wadler:
+    - rename ctor param `space` to `space_gen`.
+    - add `consistent` and `inconsistent` as shorthands to
+    `group(:consistent)` and `group(:inconsistent)`, respectively.
+    - remove args of `group_close`.
+    - add `do` to avoid braking call chains.
+    - `group_open` accepts a symbol `break_type` instead of a boolean.
+    - add `separate` to separate a list of items.
+    - add `space` to generate a literal space.
+    - add `surround` as a glorified `group` that add breakables next to delimiters.
+
 ## v0.9.8 (30-12-2024)
 
 - Oppen now supports Ruby 3.0+. It used to be restricted to Ruby 3.2+.

bin/repl.rb

@@ -3,17 +3,12 @@
 require 'colored'
 
 # Fancy
-WELCOME = <<-'YGM'
-   __ __   ___   __ __  ____    ____    ___  ___ ___  ____    ____  ___ ___    ___
-  |  |  | /   \ |  |  ||    \  /    |  /  _]|   |   ||    \  /    ||   |   |  /  _]
-  |  |  ||     ||  |  ||  D  )|   __| /  [_ | _   _ ||  _  ||  o  || _   _ | /  [_
-  |  ~  ||  O  ||  |  ||    / |  |  ||    _]|  \_/  ||  |  ||     ||  \_/  ||    _]
-  |___, ||     ||  :  ||    \ |  |_ ||   [_ |   |   ||  |  ||  _  ||   |   ||   [_
-  |     ||     ||     ||  .  \|     ______     ______     ______   __      ||     |
-  |____/  \___/  \__,_||__|\_||___ /\  == \   /\  ___\   /\  == \ /\ \  ___||_____|
-                                   \ \  __<   \ \  __\   \ \  _-/ \ \ \____
-                                    \ \_\ \_\  \ \_____\  \ \_\    \ \_____\
-                                     \/_/ /_/   \/_____/   \/_/     \/_____/
+WELCOME = <<~YGM
+   ___ ___ ___ ___ ___
+  | . | . | . | -_|   |
+  |___|  _|  _|___|_|_|
+      |_| |_|
+
 YGM
 
 puts WELCOME.green

examples/configs/eager_print.rb

@@ -24,7 +24,7 @@
 title 'With eager printing:'
 puts printer_with_config.output
 # abc defghi
-# jkl
+#        jkl
 
 puts ''
 

examples/configs/indent_anchor.rb

@@ -5,17 +5,19 @@
 printer_with_config =
   Oppen::Wadler.new(
     config: Oppen::Config.new(indent_anchor: :current_offset),
+    indent: 4,
     width: 13,
   )
 printer_no_config =
   Oppen::Wadler.new(
     config: Oppen::Config.new(indent_anchor: :end_of_previous_line),
+    indent: 4,
     width: 13,
   )
 test_block = ->(printer) {
   printer.text 'And she said:'
-  printer.group(4) {
-    printer.group(4) {
+  printer.group {
+    printer.group {
       printer.break
       printer.text 'Hello, World!'
     }

examples/oppen_and_wadler_customization/new_line.rb

@@ -5,9 +5,9 @@
 # The new line String can be specified using the `new_line` parameter.
 new_line = '<br>'
 
-printer = Oppen::Wadler.new(new_line: new_line)
+printer = Oppen::Wadler.new(indent: 2, new_line: new_line)
 
-printer.group(2) {
+printer.group {
   printer.text 'Hello, World!'
   printer.break
   printer.text 'How are you doing?'

examples/oppen_and_wadler_customization/space.rb

@@ -9,13 +9,13 @@
 # By using a callable:
 space = ->(n) { '---' * n }
 
-printer = Oppen::Wadler.new(space: space)
+printer = Oppen::Wadler.new(indent: 2, space_gen: space)
 
-printer.group(2) {
+printer.group {
   printer.text 'Hello, World!'
   printer.break
   printer.text 'How are you doing?'
-  printer.group(2) {
+  printer.group {
     printer.break
     printer.text 'I am fine'
   }

examples/oppen_and_wadler_customization/whitespace.rb

@@ -9,9 +9,9 @@
 # to prevent trailing whitespaces can be specified using the `whitespace` parameter.
 whitespace = '**'
 
-printer = Oppen::Wadler.new(whitespace: whitespace)
+printer = Oppen::Wadler.new(indent: 2, whitespace: whitespace)
 
-printer.group(2) {
+printer.group {
   printer.text '******Hello, World!******'
   printer.break
 }

examples/oppen_and_wadler_customization/width.rb

@@ -5,10 +5,10 @@
 # The maximum width can be specified using the `width` parameter.
 width = 5
 
-printer_width_default = Oppen::Wadler.new
-printer_width_narrow = Oppen::Wadler.new(width: width)
+printer_width_default = Oppen::Wadler.new(indent: 2)
+printer_width_narrow = Oppen::Wadler.new(indent: 2, width: width)
 test_block = ->(printer) {
-  printer.group(2) {
+  printer.group {
     printer.text 'Hello, World!'
     printer.breakable
     printer.text 'How are you doing?'

examples/show_print_commands/show_print_commands.rb

@@ -4,19 +4,21 @@
 
 printer = Oppen::Wadler.new
 
-printer.group(2) {
+printer.group(indent: 2) {
   printer.text 'Hello, World!'
-  printer.nest(4) {
+  printer.nest(indent: 4) {
     printer.break
     printer.text 'GoodBye, World!'
   }
 }
 
 puts printer.show_print_commands
-# out.group(2, "", "", :consistent) {
-#   out.text("Hello, World!", width: 13)
-#   out.nest(4, "", "") {
-#     out.break(line_continuation: "")
+# out.group(:consistent, indent: 0) {
+#   out.group(:consistent, indent: 2) {
+#     out.text("Hello, World!", width: 13)
+#     out.nest(indent: 4) {
+#       out.break(line_continuation: "")
+#     }
+#     out.text("GoodBye, World!", width: 15)
 #   }
-#   out.text("GoodBye, World!", width: 15)
 # }

examples/wadler_break_and_breakable/breakable.rb

@@ -8,7 +8,7 @@
 printer = Oppen::Wadler.new(width: 40)
 
 # See `examples/wadler_group/inconsistent.rb` for more infos about `:inconsistent`
-printer.group(0, '', '', :inconsistent) {
+printer.group(:inconsistent) {
   printer.text 'Hello, World!'
   printer.breakable
   printer.text '(still fits on the line)'

examples/wadler_group/consistent.rb

@@ -8,7 +8,7 @@
 printer = Oppen::Wadler.new(width: 999_999)
 
 # Groups are consistent by default.
-printer.group {
+printer.consistent { # alias for printer.group(:consistent) and same as printer.group
   printer.text 'Hello, World!'
   printer.breakable
   printer.text 'How are you doing?'

examples/wadler_group/delimiters.rb

@@ -2,10 +2,10 @@
 
 require_relative '../helper'
 
-printer = Oppen::Wadler.new(width: 999_999)
+printer = Oppen::Wadler.new(indent: 2, width: 999_999)
 
 # Groups have no delimiters by default.
-printer.group(2, '<<', '>>') {
+printer.group(delim: %w[<< >>]) {
   printer.text 'Hello, World!'
   printer.break
   printer.text 'How are you doing?'
@@ -16,6 +16,7 @@
 }
 
 puts printer.output
+#
 #   <<Hello, World!
 #   How are you doing?
 #   I am fine, thanks.

examples/wadler_group/inconsistent.rb

@@ -7,7 +7,7 @@
 
 printer = Oppen::Wadler.new(width: 999_999)
 
-printer.group(0, '', '', :inconsistent) {
+printer.inconsistent { # alias for printer.group(:inconsistent)
   printer.text 'Hello, World!'
   printer.breakable
   printer.text 'How are you doing?'

examples/wadler_group/indentation.rb

@@ -2,10 +2,10 @@
 
 require_relative '../helper'
 
-printer = Oppen::Wadler.new(width: 999_999)
+printer = Oppen::Wadler.new(indent: 4, width: 999_999)
 
 # Groups have an indentation of 0 by default.
-printer.group(4) {
+printer.group {
   printer.text 'Hello, World!'
   printer.break
   printer.text 'How are you doing?'

examples/wadler_nest/delimiters.rb

@@ -2,10 +2,10 @@
 
 require_relative '../helper'
 
-printer = Oppen::Wadler.new(width: 999_999)
+printer = Oppen::Wadler.new(indent: 2, width: 999_999)
 
 # Nests have no delimiters by default.
-printer.nest(2, '<<', '>>') {
+printer.nest(delim: %w[<< >>]) {
   printer.text 'Hello, World!'
   printer.break
   printer.text 'How are you doing?'

examples/wadler_nest/indentation.rb

@@ -2,9 +2,9 @@
 
 require_relative '../helper'
 
-printer = Oppen::Wadler.new(width: 999_999)
+printer = Oppen::Wadler.new(indent: 4, width: 999_999)
 
-printer.nest(4) {
+printer.nest {
   printer.text 'Hello, World!'
   printer.break
   printer.text 'How are you doing?'

examples/wadler_utils/separate.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative '../helper'
+
+# You might want to also take a look at the `lines` and `concat` methods.
+
+printer = Oppen::Wadler.new(width: 10)
+
+printer.separate((1..10).map(&:to_s), ',', break_type: :inconsistent, indent: 2) { |i|
+  printer.text i
+}
+
+puts printer.output
+# 1, 2, 3,
+#   4, 5, 6,
+#   7, 8, 9,
+#   10

examples/wadler_utils/surround.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative '../helper'
+
+# You might want to also take a look at the `parens`, `parens_break_both`, `angles`, ... methods.
+
+printer = Oppen::Wadler.new(width: 10)
+
+printer.surround('<<', '>>', indent: 2, lft_force_break: true, rgt_force_break: true) {
+  printer.text '42'
+}
+
+puts printer.output
+# <<
+#   42
+#   >>

justfile

@@ -30,6 +30,12 @@ doc:
 doc-stats:
   bundle exec yard stats --list-undoc
 
+[group('test')]
+examples:
+  find examples/ -mindepth 2 -type f -name "*.rb" | while IFS= read -r file; do \
+    bundle exec ruby "$file" > /dev/null || exit 1; \
+  done
+
 [group('publish')]
 gem:
   mkdir -p {{PKG_OUT}}

lib/oppen.rb

@@ -64,8 +64,8 @@ class Config
     #   config = Oppen::Config.new(indent_anchor: :end_of_previous_line)
     #   out = Oppen::Wadler.new config:, width: 13
     #   out.text 'And she said:'
-    #   out.group(4) {
-    #     out.group(4) {
+    #   out.group(indent: 4) {
+    #     out.group(indent: 4) {
     #       out.break
     #       out.text 'Hello, World!'
     #     }
@@ -80,8 +80,8 @@ class Config
     #   config = Oppen::Config.new(indent_anchor: :current_offset)
     #   out = Oppen::Wadler.new config:, width: 13
     #   out.text 'And she said:'
-    #   out.group(4) {
-    #     out.group(4) {
+    #   out.group(indent: 4) {
+    #     out.group(indent: 4) {
     #       out.break
     #       out.text 'Hello, World!'
     #     }
@@ -123,7 +123,7 @@ def initialize(eager_print: false, indent_anchor: :end_of_previous_line,
     #   #
     #   # eager_print: true =>
     #   # abc defghi
-    #   # jkl
+    #   #        jkl
     #
     # @return [Boolean]
     def eager_print? = @eager_print