oppen 0.9.8 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '008545ae6d86a7415e434ef51a19872fbf5b768db232d70bbac025667e002604'
-  data.tar.gz: a989a6e8d422c363e7ebca36fc10dac4ad030f145afc2b4bc152c9cff5bdfe49
+  metadata.gz: e53fd2f0875228c91da4aaa2259d7b1bf18e0561284513e57181cb6c260ba610
+  data.tar.gz: 82c1776d841d6eef2d2071fc923b4864e23e2e68e079fa6caec36b7cca23ffbc
 SHA512:
-  metadata.gz: 9a3e32d3a05c638bd26a9e170d737186c9635eeb3c54844869b108c8252fdafa942a05a76a1e3d3d25d5e93a47d076c280f7346c1c313b5c7159a8f3d1166ef6
-  data.tar.gz: 1f3c076ea8b298f5a772d9c209c4bc64087f6093576e41e2ffb6289b5d0aba08c1b3ed9d3022ebb14b7d7fe4c083804e60219735bce5c00f96785e9dede2bb69
+  metadata.gz: 87f3293a723b93c82532045aafe0dd699b6d7ac754893d51ff338448550187f27d75d7bea12fd4035be3f765de660605c56ac431460785387b47b6955b2805bb
+  data.tar.gz: 9928e9536e2fb193150fb32d000abf5e5b0017cbbecab050b2b064f14847f72b24ac573ea4779d2fe0bd2f5ac4f5b1ef04a7b1341bdc36e9b74bd652aa3b43ce

data/README.md

@@ -22,16 +22,12 @@ transition from `ruby/prettyprint` to this gem.
 
 `Wadler` is implemented on top of `Oppen`, and it provides more options than
 `ruby/prettyprint`, notably:
-1. Consistent and inconsistent breaking.
-1. Explicit breaking, which is achievable in `ruby/prettyprint` with some
-monkeypatching.
-
-> [!CAUTION]
-> This is still under development.
-
-## Usage
-
-A few examples of the API usage can be found in [examples/](examples/README.md).
+1. [Consistent](examples/wadler_group/consistent.rb) and [inconsistent](examples/wadler_group/inconsistent.rb) breaking.
+1. [Explicit breaking](examples/wadler_break_and_breakable/break.rb), which is achievable in `ruby/prettyprint` with some monkeypatching.
+1. [Trimming of trailing whitespaces](examples/oppen_and_wadler_customization/whitespace.rb).
+1. [Display a `String` on line break](examples/wadler_break_and_breakable/line_continuation.rb).
+1. A bunch of helper methods to simplify common patterns like [surrounding](examples/wadler_utils/surround.rb) or
+[separating](examples/wadler_utils/surround.rb) tokens.
 
 ## Oppen vs Wadler
 
@@ -39,34 +35,109 @@ A few examples of the API usage can be found in [examples/](examples/README.md).
 and it's not calling ruby's `prettyprint`.
 
 Both implementations have their use cases:
-1. Oppen gives more control over tokens sent to the printer.
-1. Wadler gives a more _"functional"_ API, which is far nicer to work with.
+- Oppen gives more control over tokens sent to the printer.
+- Wadler gives a more _"functional"_ API, which is far nicer to work with.
 
 That being said, both APIs in this gem can achieve the same results, especially
 on consistent and inconsistent breaking.
 
-## Noteworthy details
-
-### Difference with Oppen's original algorithm
-
-1. We took liberty to rename functions to make the API more modern and closer to
+## Oppen's API Example
+
+```ruby
+tokens = [
+  Oppen.begin_inconsistent,
+  Oppen.string('Hello'),
+  Oppen.break(', '),
+  Oppen.string('World!'),
+  Oppen.line_break,
+  Oppen.string('How are you doing?'),
+  Oppen.end,
+  Oppen.eof,
+]
+
+puts Oppen.print(tokens:)
+# Hello, World!
+#   How are you doing?
+```
+
+## Wadler's API Example
+
+```ruby
+out = Oppen::Wadler.new(width: 20)
+
+out.group(indent: 2) {
+  out.group {
+    out.text('def').breakable.text('foo')
+  }
+  out.parens_break_none {
+    out.separate(%w[bar baz bat qux], ',', break_type: :inconsistent) { |param|
+      out.text(param)
+    }
+  }
+}
+out.group(indent: 2) {
+  out
+    .break
+    .nest(indent: 2) {
+      out
+        .text('puts')
+        .breakable(line_continuation: ' \\')
+        .text('42')
+  }
+}
+out.break.text('end')
+
+puts out.output
+# def foo(bar, baz,
+#   bat, qux)
+#   puts \
+#     42
+# end
+```
+
+## More Examples
+
+An easy way to add colors to the output on the terminal is wrap `oppen` and expose your own vocabulary:
+
+```ruby
+require 'colored'
+class ColoredTty
+  KW_PALETTE = { Hello: :red, World: :green }.freeze
+  def initialize(...) = @out = Oppen::Wadler.new(...)
+  def breakable(...) = @out.breakable(...) && self
+  def keyword(value, width: value.length) = @out.text(value.send(KW_PALETTE[value.to_sym] || :white), width:) && self
+  def output = @out.output
+  def text(...) = @out.text(...) && self
+end
+
+out = ColoredTty.new(width: 12)
+out.keyword('Hello').breakable.text('World')
+
+puts out.output
+# \e[31mHello\e[0m World
+```
+
+The same idea can be applied an adapted to make an HTML printer; all you need to take care of is the correct width of the text to preserve the width of the text and get an output identical to that of the tty colored printer.
+
+Check out the [examples/](examples/README.md) folder for more details on how to use the Oppen and Wadler APIs.
+
+## Difference With Oppen's Original Algorithm
+
+1. We took the liberty to rename functions to make the API more modern and closer to
 what we expect when writing Ruby code.  All correspondences with the algorithm
 as described in Oppen's paper are noted in the comments of classes and methods.
 1. We do not raise exceptions when we overflow the margin. The only exceptions
 that we raise indicate a bug in the implementation. Please report them.
+1. The stacks described by the algorithm do not have a fixed size in our
+implementation: we upsize them when they are full.
+1. We can optionally trim trailing whitespaces (this feature is on by default for the `Wadler` API).
+1. We added support for an additional new line anchors, see [examples/configs/indent_anchor.rb](examples/configs/indent_anchor.rb).
+1. We added support for eager printing of `groups`; see [examples/configs/eager_print.rb](examples/configs/eager_print.rb).
+1. We introduced a new token (`Whitespace`) and added more customizations to one of the originals (`Break`).
 
-### Difference with `ruby/prettyprint`
-
-Oppen's algorithm and `ruby/prettyprint` do not have the same starting positions
-for a group's indentation. That's why you need to pay particular attention to
-calls for `nest`; you might want to decrease them by `1` if you care about keeping
-the same behavior.
-
-This is what we do in our test suite to verify the correspondence of the `Wadler`
-API and the `ruby/prettyprint`. We decided to shift the burden to the user because
-we think that the deicision taken by `ruby/prettyprint` does not suit us.
+For more insight on how Oppen's algorithm works, check out [docs/oppen_algorithm.md](docs/oppen_algorithm.md).
 
-## Related projects
+## Related Projects
 
 1. [`ruby/prettyprint`](https://github.com/ruby/prettyprint)
 1. [rustc implementation](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast_pretty/pp/index.html)

data/lib/oppen/mixins.rb

@@ -24,15 +24,14 @@ module Oppen
 
     # @return [String]
     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
+      printer = Oppen::Wadler.new(base_indent:, indent: 2, width:)
 
       handle_break_token = ->(token) {
         if token.offset.positive?
-          printer.text "#{printer_name}.nest(#{token.offset}, '', '') {"
-          printer.nest_open indent
-          printer.break
+          printer
+            .text("#{printer_name}.nest(indent: #{token.offset}) {")
+            .nest_open
+            .break
         end
 
         printer.text(
@@ -45,11 +44,7 @@ module Oppen
           end,
         )
 
-        if token.offset.positive?
-          printer.nest_close indent
-          printer.break
-          printer.text '}'
-        end
+        printer.nest_close.break.text '}' if token.offset.positive?
       }
 
       tokens.each_with_index do |token, idx|
@@ -59,17 +54,17 @@ module Oppen
         in Token::Break
           handle_break_token.(token)
         in Token::Begin
-          printer.text "#{printer_name}.group(#{token.offset}, '', '', #{token.break_type.inspect}) {"
-          printer.nest_open indent
+          printer
+            .text("#{printer_name}.group(#{token.break_type.inspect}, indent: #{token.offset}) {")
+            .nest_open
         in Token::End
-          printer.nest_close indent
-          printer.break
-          printer.text '}'
+          printer.nest_close.break.text '}'
         in Token::EOF
           nil
         end
         printer.break if !tokens[idx + 1].is_a?(Token::End)
       end
+
       printer.output
     end
   end

data/lib/oppen/print_stack.rb

@@ -81,7 +81,7 @@ module Oppen
       in Token::End
         handle_end
       in Token::Break
-        handle_break token, token_width, trim_on_break: trim_on_break
+        handle_break token, token_width, trim_on_break:
       in Token::String
         handle_string token, token_width
       end

data/lib/oppen/printer.rb

@@ -293,7 +293,7 @@ module Oppen
         end
       trim_on_break ||= 0
 
-      print_stack.print(token, token_width, trim_on_break: trim_on_break)
+      print_stack.print(token, token_width, trim_on_break:)
 
       case token
       when Token::Break

data/lib/oppen/token.rb

@@ -74,7 +74,7 @@ module Oppen
       end
 
       def initialize(line_continuation: '', offset: 0)
-        super(LineBreakString.new, line_continuation: line_continuation, offset: offset)
+        super(LineBreakString.new, line_continuation:, offset:)
       end
     end
 

data/lib/oppen/version.rb

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

data/lib/oppen.rb

@@ -64,8 +64,8 @@ module Oppen
     #   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 @@ module Oppen
     #   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 @@ module Oppen
     #   #
     #   # eager_print: true =>
     #   # abc defghi
-    #   # jkl
+    #   #        jkl
     #
     # @return [Boolean]
     def eager_print? = @eager_print
@@ -154,10 +154,10 @@ module Oppen
     # @return [Config]
     def self.wadler(eager_print: true, trim_trailing_whitespaces: true, upsize_stack: true)
       new(
-        eager_print: eager_print,
+        eager_print:,
         indent_anchor: :current_offset,
-        trim_trailing_whitespaces: trim_trailing_whitespaces,
-        upsize_stack: upsize_stack,
+        trim_trailing_whitespaces:,
+        upsize_stack:,
       )
     end
   end
@@ -172,7 +172,7 @@ module Oppen
   # @return [Token::String]
   #   a new String token.
   def self.string(value, width: value.length)
-    Token::String.new(value, width: width)
+    Token::String.new(value, width:)
   end
 
   # @return [Token::Whitespace] a new Whitespace token.
@@ -196,7 +196,7 @@ module Oppen
   #
   # @see Wadler#break example on `line_continuation`.
   def self.break(str = ' ', line_continuation: '', offset: 0, width: str.length)
-    Token::Break.new(str, width: width, line_continuation: line_continuation, offset: offset)
+    Token::Break.new(str, width:, line_continuation:, offset:)
   end
 
   # @param line_continuation [String]
@@ -209,7 +209,7 @@ module Oppen
   #
   # @see Wadler#break example on `line_continuation`.
   def self.line_break(line_continuation: '', offset: 0)
-    Token::LineBreak.new(line_continuation: line_continuation, offset: offset)
+    Token::LineBreak.new(line_continuation:, offset:)
   end
 
   # In a consistent group, the presence of a new line inside the group will
@@ -232,7 +232,7 @@ module Oppen
   #
   # @see Wadler#group
   def self.begin_consistent(offset: 2)
-    Token::Begin.new(break_type: :consistent, offset: offset)
+    Token::Begin.new(break_type: :consistent, offset:)
   end
 
   # In an inconsistent group, the presence of a new line inside the group will
@@ -251,7 +251,7 @@ module Oppen
   #
   # @see Wadler#group
   def self.begin_inconsistent(offset: 2)
-    Token::Begin.new(break_type: :inconsistent, offset: offset)
+    Token::Begin.new(break_type: :inconsistent, offset:)
   end
 
   # @return [Token::End] a new End token.

data/lib/wadler/print.rb

@@ -18,7 +18,7 @@ module Oppen
     attr_reader :out
     # @return [Proc]
     #   space generator, a callable.
-    attr_reader :space
+    attr_reader :space_gen
     # @return [Array<Token>]
     #   the tokens list that is being built.
     attr_reader :tokens
@@ -29,13 +29,17 @@ module Oppen
     #   maximum line width.
     attr_reader :width
 
+    # @param base_indent     [Integer]
+    #   the starting indentation level for the whole printer.
     # @param config     [Config]
     #   to customize the printer's behavior.
+    # @param indent     [Integer]
+    #   the default indentation amount for {group} and {nest}.
     # @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]
+    # @param space_gen  [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.
@@ -44,27 +48,26 @@ module Oppen
     # @param width      [Integer]      maximum line width desired.
     #
     # @see Token::Whitespace
-    def initialize(config: Config.wadler, new_line: "\n",
-                   out: StringIO.new, space: ' ',
+    def initialize(base_indent: 0, config: Config.wadler, indent: 0, new_line: "\n",
+                   out: StringIO.new, space_gen: ' ',
                    whitespace: ' ', width: 80)
       @config = config
-      @current_indent = 0
-      @space = space
-      @width = width
+      @current_indent = base_indent
+      @indent = indent
       @new_line = new_line
       @out = out
+      @space_gen = space_gen
       @tokens = []
       @whitespace = whitespace
+      @width = width
     end
 
     # Add missing {Token::Begin}, {Token::End} or {Token::EOF}.
     #
     # @return [Nil]
     def add_missing_begin_and_end
-      if !tokens.first.is_a? Token::Begin
-        tokens.unshift Oppen.begin_consistent(offset: 0)
-        tokens << Oppen.end
-      end
+      tokens.unshift Oppen.begin_consistent(offset: 0)
+      tokens << Oppen.end
       tokens << Oppen.eof if !tokens.last.is_a?(Oppen::Token::EOF)
     end
 
@@ -74,12 +77,12 @@ module Oppen
     def output
       add_missing_begin_and_end
       Oppen.print(
-        tokens: tokens,
-        new_line: new_line,
-        config: config,
-        space: space,
-        out: out,
-        width: width,
+        tokens:,
+        new_line:,
+        config:,
+        space: space_gen,
+        out:,
+        width:,
       )
     end
 
@@ -96,13 +99,11 @@ module Oppen
     #
     # @example
     #   out = Oppen::Wadler.new
-    #   out.group {
-    #     out.text('Hello World!')
-    #   }
+    #   out.text('Hello World!')
     #   out.show_print_commands(out_name: 'out')
     #
     #   # =>
-    #   # out.group(0, "", "", :consistent) {
+    #   # out.group(:consistent, indent: 0) {
     #   #   out.text("Hello World!", width: 12)
     #   # }
     #
@@ -114,26 +115,57 @@ module Oppen
 
     # Create a new group.
     #
-    # @param indent     [Integer]
+    # @param indent    [Integer]
     #   indentation.
-    # @param open_obj   [String]
-    #   opening delimiter.
-    # @param close_obj  [String]
-    #   closing delimiter.
+    # @param delim     [Nil|String|Symbol|Array<Nil, String, Symbol>]
+    #   delimiters, to be printed at the start and the end of the group:
+    #   - If it's nil, nothing will be printed
+    #   - If it's a Strings or a Symbol, it will be printed at both positions.
+    #   - If it's an Array of many items, the first two elements will be used
+    #     for the start and end of the group.
     # @param break_type [Token::BreakType]
     #   break type.
     #
     # @yield
     #   the block of text in a group.
     #
-    # @example
+    # @example 1 String Delimiter
     #   out = Oppen::Wadler.new
-    #   out.text 'a'
-    #   out.group(2, '{', '}') {
-    #     out.break
-    #     out.text 'b'
-    #   }
-    #   out.output
+    #   out
+    #     .text('a')
+    #     .group(indent: 2, delim: '|') {
+    #       out.break.text 'b'
+    #     }
+    #   puts out.output
+    #
+    #   # =>
+    #   # a
+    #   #   |
+    #   #   b
+    #   #   |
+    #
+    # @example 1 Delimiter in Array
+    #   out = Oppen::Wadler.new
+    #   out
+    #     .text('a')
+    #     .group(indent: 2, delim: ['|']) {
+    #       out.break.text 'b'
+    #     }
+    #   puts out.output
+    #
+    #   # =>
+    #   # a
+    #   #   |
+    #   #   b
+    #
+    # @example 2 Delimiters
+    #   out = Oppen::Wadler.new
+    #   out
+    #     .text('a')
+    #     .group(indent: 2, delim: %i[{ }]) {
+    #       out.break.text 'b'
+    #     }
+    #   puts out.output
     #
     #   # =>
     #   # a
@@ -143,14 +175,10 @@ module Oppen
     #
     # @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.group(:consistent) {
+    #     out.text('a').break.text('b').breakable.text('c')
     #   }
-    #   out.output
+    #   puts out.output
     #
     #   # =>
     #   # a
@@ -159,27 +187,26 @@ module Oppen
     #
     # @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.group(:inconsistent) {
+    #     out.text('a').break.text('b').breakable.text('c')
     #   }
-    #   out.output
+    #   puts out.output
     #
     #   # =>
     #   # a
     #   # b c
     #
-    # @return [Nil]
+    # @return [self]
     #
     # @see Oppen.begin_consistent
     # @see Oppen.begin_inconsistent
-    def group(indent = 0, open_obj = '', close_obj = '',
-              break_type = :consistent)
-      raise ArgumentError, "#{open_obj.nil? ? 'open_obj' : 'close_obj'} cannot be nil" \
-        if open_obj.nil? || close_obj.nil?
+    def group(break_type = :consistent, delim: nil, indent: @indent)
+      lft, rgt =
+        case delim
+        in nil then ['', '']
+        in String | Symbol then [delim, delim]
+        in Array then delim.values_at(0, 1).map(&:to_s)
+        end
 
       tokens <<
         case break_type
@@ -189,19 +216,31 @@ module Oppen
           Oppen.begin_inconsistent(offset: indent)
         end
 
-      if !open_obj.empty?
+      if !lft.empty?
         self.break
-        text(open_obj)
+        text lft
       end
 
       yield
 
-      if !close_obj.empty?
+      if !rgt.empty?
         self.break
-        text(close_obj)
+        text rgt
       end
 
       tokens << Oppen.end
+
+      self
+    end
+
+    # An alias for `group(:consistent, ...)`
+    def consistent(...)
+      group(:consistent, ...)
+    end
+
+    # An alias for `group(:inconsistent, ...)`
+    def inconsistent(...)
+      group(:inconsistent, ...)
     end
 
     # Create a new non-strict {group}.
@@ -218,24 +257,24 @@ module Oppen
     # @note a {nest} will not forcibly indent its content if the break type of
     # the enclosing {group} is `:inconsistent`.
     #
-    # @param indent    [Integer]
+    # @param delim [Nil|String|Symbol|Array<Nil, String, Symbol>]
+    #   delimiters, to be printed at the start and the end of the group:
+    #   - `nil` is always the empty string.
+    #   - If it's a Strings or a Symbol, it will be printed at both positions.
+    #   - If it's an Array of many items, the first two elements will be used
+    #     for the start and end of the group.
+    # @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.nest(delim: %i[{ }], indent: 2) {
+    #     out.text('a').break.text('b')
     #   }
-    #   out.output
+    #   puts out.output
     #
     #   # =>
     #   # {
@@ -243,15 +282,19 @@ module Oppen
     #   #   b
     #   # }
     #
-    # @return [Nil]
-    def nest(indent, open_obj = '', close_obj = '')
-      raise ArgumentError, "#{open_obj.nil? ? 'open_obj' : 'close_obj'} cannot be nil" \
-        if open_obj.nil? || close_obj.nil?
+    # @return [self]
+    def nest(delim: nil, indent: @indent)
+      lft, rgt =
+        case delim
+        in nil then ['', '']
+        in String | Symbol then [delim, delim]
+        in Array then delim.values_at(0, 1).map(&:to_s)
+        end
 
       @current_indent += indent
 
-      if !open_obj.empty?
-        text(open_obj)
+      if !lft.empty?
+        text lft
         self.break
       end
 
@@ -261,10 +304,12 @@ module Oppen
         @current_indent -= indent
       end
 
-      return if close_obj.empty?
+      if !rgt.empty?
+        self.break
+        text rgt
+      end
 
-      self.break
-      text(close_obj)
+      self
     end
 
     # Create a new text element.
@@ -272,7 +317,7 @@ module Oppen
     # @param value [String]
     #   the value of the token.
     #
-    # @return [Nil]
+    # @return [self]
     def text(value, width: value.length)
       if config.trim_trailing_whitespaces? && value.match(/((?:#{Regexp.escape(whitespace)})+)\z/)
         match = Regexp.last_match(1)
@@ -282,8 +327,9 @@ module Oppen
         end
         tokens << Oppen.whitespace(match)
       else
-        tokens << Oppen.string(value, width: width)
+        tokens << Oppen.string(value, width:)
       end
+      self
     end
 
     # Create a new breakable element.
@@ -295,11 +341,12 @@ module Oppen
     # @param width             [Integer]
     #   the width of the token.
     #
-    # @return [Nil]
+    # @return [self]
     #
     # @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)
+      tokens << Oppen.break(str, width:, line_continuation:, offset: current_indent)
+      self
     end
 
     # Create a new break element.
@@ -314,55 +361,424 @@ module Oppen
     #   out.text 'b'
     #   out.break line_continuation: '#'
     #   out.text 'c'
-    #   out.output
+    #   puts out.output
     #
     #   # =>
     #   # a
     #   # b#
     #   # c
     #
-    # @return [Nil]
+    # @return [self]
     def break(line_continuation: '')
-      tokens << Oppen.line_break(line_continuation: line_continuation, offset: current_indent)
+      tokens << Oppen.line_break(line_continuation:, offset: current_indent)
+      self
+    end
+
+    # A convenient way to avoid breaking chains of calls.
+    #
+    # @example
+    #   out
+    #     .do { fn_call(fn_arg) }
+    #     .breakable
+    #     .text('=')
+    #     .breakable
+    #     .do { fn_call(fn_arg) }
+    #
+    # @yield to execute the passed block
+    #
+    # @return [self]
+    def do
+      yield
+      self
     end
 
-    # @!group Helpers
+    # A means to wrap a piece of code in several ways.
+    #
+    # @example
+    #   out
+    #     .wrap {
+    #       # all printing instructions here will be deferred.
+    #       # they will be executed in `when` blocks by calling the `wrapped`.
+    #       out.text(...)
+    #       # ...
+    #     } # This is "wrapped".
+    #     .when(cond1){ |wrapped|
+    #       # when cond1 is true you execute this block.
+    #       out.text("before wrapped")
+    #       # call the wrapped
+    #       wrapped.call
+    #       # and continue printing
+    #       out.text("after wrapped)
+    #     }
+    #     .when(cond2){ |wrapped|
+    #       # and you cand define many conditions.
+    #     }
+    #     .end
+    #
+    # @example Calling `end` is not needed if there's another call after the last `when`:
+    #   out
+    #     .wrap{...} # This is "wrapped".
+    #     .when(cond1){ |wrapped| ... }
+    #     .when(cond2){ |wrapped| ... }
+    #     .text('foo')
+    #
+    # @return [Wrap]
+    def wrap(&blk)
+      Wrap.new(blk)
+    end
 
-    # Set a base indenetaion level for the printer.
+    # Produce a separated list.
     #
-    # @param indent [Integer]
-    #   the amount of indentation.
+    # @example Consistent Breaking
+    #  puts out.separate((1..3).map(&:to_s), ',') { |i| out.text i}
     #
-    # @return [Nil]
-    def base_indent(indent = 0)
-      @current_indent = indent if !indent.nil?
+    #  # =>
+    #  # 1,
+    #  # 2,
+    #  # 3
+    #
+    # @example Inconsistent Breaking
+    #  puts out.separate((1..3).map(&:to_s), ',', break_type: :inconsistent) { |i| out.text i}
+    #
+    #  # =>
+    #  # 1, 2,
+    #  # 3
+    #
+    # @param args              [String]
+    #   a list of values.
+    # @param sep               [String]
+    #   a separator.
+    # @param breakable         [String|Nil]
+    #   adds a `breakable` after the separator.
+    # @param break_pos         [Symbol]
+    #   whether to break :before or :after the seraparator.
+    # @param break_type        [Symbol|Nil]
+    #   whether the break is :consistent or :inconsistent.
+    #   If nil is given, the tokens will not be surrounded by a group.
+    # @param indent            [Boolean|Integer]
+    #   - If `true`, indent by @indent.
+    #   - If an 'Integer', indent by its value.
+    # @param force_break       [Boolean]
+    #   adds a `break` after the separator.
+    # @param line_continuation [String]
+    #   string to display before new line.
+    #
+    # @yield to execute the passed block.
+    #
+    # @return [self]
+    def separate(args, sep, breakable: ' ', break_pos: :after,
+                 break_type: nil, indent: false,
+                 force_break: false, line_continuation: '')
+      if args.is_a?(Enumerator) ? args.count == 1 : args.length == 1
+        yield(*args[0])
+        return self
+      end
+
+      first = true
+      wrap {
+        wrap {
+          args&.each do |*as|
+            if first
+              breakable '' if !line_continuation.empty? && break_pos == :after
+              first = false
+            elsif break_pos == :after
+              text sep
+              breakable(breakable, line_continuation:) if breakable && !force_break
+              self.break(line_continuation:) if force_break
+            else
+              breakable(breakable, line_continuation:) if breakable && !force_break
+              self.break(line_continuation:) if force_break
+              text sep
+            end
+            yield(*as)
+          end
+        }
+          .when(break_type) { |body|
+            group(break_type, indent: 0) {
+              body.()
+            }
+          }
+          .end
+      }
+        .when(indent) { |body|
+          nest(indent: indent.is_a?(Integer) ? indent : @indent) {
+            body.()
+          }
+        }.end
+      breakable('', line_continuation:) if !line_continuation.empty? && !break_type
+
+      self
+    end
+
+    # A shorhand for `text ' '`.
+    #
+    # @return [self]
+    def space
+      text ' '
+    end
+
+    # Surround a block with +lft+ and +rgt+
+    #
+    # @param lft [String]  lft
+    #   left surrounding string.
+    # @param rgt [String]  rgt
+    #   right surrounding string.
+    #
+    # @yield the passed block to be surrounded with `lft` and `rgt`.
+    #
+    # @option opts [Boolean] :group           (true)
+    #   whether to create a group enclosing `lft`, `rgt`, and the passed block.
+    # @option opts [Boolean] :indent          (@indent)
+    #   whether to indent the passed block.
+    # @option opts [String]  :lft_breakable   ('')
+    #   left breakable string.
+    # @option opts [Boolean] :lft_can_break   (true)
+    #   injects `break` or `breakable` only if true;
+    #   i.e. `lft_breakable` will be ignored if false.
+    # @option opts [Boolean] :lft_force_break (false)
+    #   force break instead of using `lft_breakable`.
+    # @option opts [String]  :rgt_breakable   ('')
+    #   right breakable string.
+    # @option opts [Boolean] :rgt_can_break   (true)
+    #   injects `break` or `breakable` only if true.
+    #   i.e. `rgt_breakable` will be ignored if false.
+    # @option opts [Boolean] :rgt_force_break (false)
+    #   force break instead of using `rgt_breakable`.
+    #
+    # @return [self]
+    def surround(lft, rgt, **opts)
+      group = opts.fetch(:group, true)
+      group_open(break_type: :inconsistent) if group
+
+      text lft if lft
+
+      indent = opts.fetch(:indent, @indent)
+      nest_open(indent:)
+
+      lft_breakable = opts.fetch(:lft_breakable, '')
+      lft_can_break = opts.fetch(:lft_can_break, true)
+      lft_force_break = opts.fetch(:lft_force_break, false)
+      if lft && lft_can_break
+        if lft_force_break
+          self.break
+        else
+          breakable lft_breakable
+        end
+      end
+
+      if block_given?
+        yield
+      end
+
+      nest_close
+
+      rgt_breakable = opts.fetch(:rgt_breakable, '')
+      rgt_can_break = opts.fetch(:rgt_can_break, true)
+      rgt_force_break = opts.fetch(:rgt_force_break, false)
+      if rgt
+        if rgt_can_break
+          if rgt_force_break
+            self.break
+          else
+            breakable rgt_breakable
+          end
+        end
+        text rgt
+      end
+
+      group_close if group
+
+      self
+    end
+
+    # @!group Convenience Methods Built On {separate}
+
+    # Separate args into lines.
+    #
+    # This is a wrapper around {separate} where `breakable: true`.
+    #
+    # @see [separate]
+    def lines(*args, **kwargs, &)
+      separate(*args, **kwargs.merge(force_break: true), &)
+    end
+
+    # Concatenates args.
+    #
+    # This is a wrapper around {separate} where `breakable: false`.
+    #
+    # @see [separate]
+    def concat(*args, **kwargs, &)
+      separate(*args, **kwargs.merge(breakable: false), &)
+    end
+
+    # @!endgroup
+    # @!group Convenience Methods Built On {surround}
+
+    # YARD doesn't drop into blocks, so we can't use metaprogramming
+    # to generate all these functions, so we're copy-pastring.
+
+    # {surround} with `< >`. New lines can appear after and before the delimiters.
+    #
+    # @param padding [String] ('')
+    #   Passed to `lft_breakable` and `rgt_breakable`.
+    #
+    # @return [self]
+    def angles(padding: '', **kwargs, &block)
+      surround(
+        '<', '>',
+        **kwargs.merge(lft_breakable: padding, rgt_breakable: padding),
+        &block
+      )
+    end
+
+    # {surround} with `< >`. New lines cannot appear after and before the delimiters.
+    #
+    # @return [self]
+    def angles_break_both(**kwargs, &)
+      angles(**kwargs.merge(lft_force_break: true, rgt_force_break: true), &)
+    end
+
+    # {surround} with `< >`. New lines will appear after and before the delimiters.
+    #
+    # @return [self]
+    def angles_break_none(**kwargs, &)
+      angles(**kwargs.merge(lft_can_break: false, rgt_can_break: false), &)
+    end
+
+    # {surround} with `{ }`. New lines can appear after and before the delimiters.
+    #
+    # @param padding [String] ('')
+    #   Passed to `lft_breakable` and `rgt_breakable`.
+    #
+    # @return [self]
+    def braces(padding: '', **kwargs, &block)
+      surround(
+        '{', '}',
+        **kwargs.merge(lft_breakable: padding, rgt_breakable: padding),
+        &block
+      )
+    end
+
+    # {surround} with `{ }`. New lines cannot appear after and before the delimiters.
+    #
+    # @return [self]
+    def braces_break_both(**kwargs, &)
+      braces(**kwargs.merge(lft_force_break: true, rgt_force_break: true), &)
+    end
+
+    # {surround} with `{ }`. New lines will appear after and before the delimiters.
+    #
+    # @return [self]
+    def braces_break_none(**kwargs, &)
+      braces(**kwargs.merge(lft_can_break: false, rgt_can_break: false), &)
+    end
+
+    # {surround} with `[ ]`. New lines can appear after and before the delimiters.
+    #
+    # @param padding [String] ('')
+    #   Passed to `lft_breakable` and `rgt_breakable`.
+    #
+    # @return [self]
+    def brackets(padding: '', **kwargs, &block)
+      surround(
+        '[', ']',
+        **kwargs.merge(lft_breakable: padding, rgt_breakable: padding),
+        &block
+      )
+    end
+
+    # {surround} with `[ ]`. New lines cannot appear after and before the delimiters.
+    #
+    # @return [self]
+    def brackets_break_both(**kwargs, &)
+      brackets(**kwargs.merge(lft_force_break: true, rgt_force_break: true), &)
+    end
+
+    # {surround} with `[ ]`. New lines will appear after and before the delimiters.
+    #
+    # @return [self]
+    def brackets_break_none(**kwargs, &)
+      brackets(**kwargs.merge(lft_can_break: false, rgt_can_break: false), &)
+    end
+
+    # {surround} with `( )`. New lines can appear after and before the delimiters.
+    #
+    # @param padding [String] ('')
+    #   Passed to `lft_breakable` and `rgt_breakable`.
+    #
+    # @return [self]
+    def parens(padding: '', **kwargs, &block)
+      surround(
+        '(', ')',
+        **kwargs.merge(lft_breakable: padding, rgt_breakable: padding),
+        &block
+      )
+    end
+
+    # {surround} with `( )`. New lines cannot appear after and before the delimiters.
+    #
+    # @return [self]
+    def parens_break_both(**kwargs, &)
+      parens(**kwargs.merge(lft_force_break: true, rgt_force_break: true), &)
+    end
+
+    # {surround} with `( )`. New lines will appear after and before the delimiters.
+    #
+    # @return [self]
+    def parens_break_none(**kwargs, &)
+      parens(**kwargs.merge(lft_can_break: false, rgt_can_break: false), &)
+    end
+
+    # {surround} with `` ` ` ``. New lines cannot appear after and before the delimiters
+    # unless you specify it with `rgt_can_break` and `lft_can_break`.
+    #
+    # @return [self]
+    def backticks(**kwargs, &)
+      surround('`', '`', lft_can_break: false, rgt_can_break: false, **kwargs, &)
+    end
+
+    # {surround} with `" "`. New lines cannot appear after and before the delimiters
+    # unless you specify it with `rgt_can_break` and `lft_can_break`.
+    #
+    # @return [self]
+    def quote_double(**kwargs, &)
+      surround('"', '"', lft_can_break: false, rgt_can_break: false, **kwargs, &)
+    end
+
+    # {surround} with `' '`. New lines cannot appear after and before the delimiters
+    # unless you specify it with `rgt_can_break` and `lft_can_break`.
+    #
+    # @return [self]
+    def quote_single(**kwargs, &)
+      surround("'", "'", lft_can_break: false, rgt_can_break: false, **kwargs, &)
     end
 
     # Open a consistent group.
     #
-    # @param inconsistent [Boolean]
-    #   whether the break type of the group should be inconsistent.
-    # @param indent       [Integer]
+    # @param break_type [Symbol]
+    #   `:consistent` or `:inconsistent`
+    # @param indent     [Integer]
     #   the amount of indentation of the group.
     #
-    # @return [Nil]
+    # @return [self]
     #
     # @see Oppen.begin_consistent
     # @see Oppen.begin_inconsistent
-    def group_open(inconsistent: false, indent: 0)
-      tokens <<
-        if inconsistent
-          Oppen.begin_inconsistent(offset: indent)
-        else
-          Oppen.begin_consistent(offset: indent)
-        end
+    def group_open(break_type: :consistent, indent: 0)
+      if %i[consistent inconsistent].none?(break_type)
+        raise ArgumentError, '%s is not a valid type. Choose one: :consistent or :inconsistent'
+      end
+
+      tokens << Oppen.send(:"begin_#{break_type}", offset: indent)
+      self
     end
 
     # Close a group.
     #
-    # @return [Nil]
-    def group_close(_)
+    # @return [self]
+    def group_close
       tokens << Oppen.end
+      self
     end
 
     # Open a consistent group and add indent amount.
@@ -370,8 +786,8 @@ module Oppen
     # @param indent [Integer]
     #   the amount of indentation of the group.
     #
-    # @return [Nil]
-    def indent_open(indent)
+    # @return [self]
+    def indent_open(indent: @indent)
       @current_indent += indent
       group_open
     end
@@ -381,10 +797,10 @@ module Oppen
     # @param indent [Integer]
     #   the amount of indentation of the group.
     #
-    # @return [Nil]
-    def indent_close(group, indent)
+    # @return [self]
+    def indent_close(indent: @indent)
       @current_indent -= indent
-      group_close(group)
+      group_close
     end
 
     # Open a nest by adding indent.
@@ -392,9 +808,10 @@ module Oppen
     # @param indent [Integer]
     #   the amount of indentation of the nest.
     #
-    # @return [Nil]
-    def nest_open(indent)
+    # @return [self]
+    def nest_open(indent: @indent)
       @current_indent += indent
+      self
     end
 
     # Close a nest by subtracting indent.
@@ -402,11 +819,43 @@ module Oppen
     # @param indent [Integer]
     #   the amount of indentation of the nest.
     #
-    # @return [Nil]
-    def nest_close(indent)
+    # @return [self]
+    def nest_close(indent: @indent)
       @current_indent -= indent
+      self
     end
 
     # @!endgroup
+
+    # Helper class to allow conditional printing.
+    class Wrap
+      def initialize(blk)
+        @wrapped = blk
+        @wrapper = nil
+      end
+
+      # Conditional.
+      def when(cond, &blk)
+        if cond
+          @wrapper = blk
+        end
+        self
+      end
+
+      # Flush.
+      def end
+        @wrapper ? @wrapper.(@wrapped) : @wrapped.()
+      end
+
+      # To re-enable chaining.
+      def method_missing(meth, ...)
+        self.end.send(meth, ...)
+      end
+
+      # To re-enable chaining.
+      def respond_to_missing?(meth, include_private)
+        self.end.respond_to_missing?(meth, include_private)
+      end
+    end
   end
 end

metadata

@@ -1,18 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: oppen
 version: !ruby/object:Gem::Version
-  version: 0.9.8
+  version: 1.0.0
 platform: ruby
 authors:
 - Amine Mike El Maalouf <amine.el-maalouf@epita.fr>
 - Firas al-Khalil <firas.alkhalil@faveod.com>
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-30 00:00:00.000000000 Z
+date: 2025-01-21 00:00:00.000000000 Z
 dependencies: []
 description: Implementation of the Oppen's pretty printing algorithm
-email: 
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -31,7 +31,7 @@ homepage: http://github.com/Faveod/oppen-ruby
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -39,7 +39,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -47,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.4.19
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Pretty-printing library
 test_files: []