oppen 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3566ebc351b729f845e192fb3687bfae4a874879b3741de2e1c43fb97946aa23
+  data.tar.gz: 9499a00567a1ad0d7f7ffc551573888513eb952945a83d90022a499d31248828
+SHA512:
+  metadata.gz: 0f1348d6dac1afc87a495f2e395ed63a28ae42a722c235f1fe33fc317f1e13b0cbe5d7cae51c67a446755a7f26382c9b7555b80e394e9bdc161e620c2fbfde44
+  data.tar.gz: 430164e1995f18e4c75cddd59e6e39f6669c9312d01d29cb9670298b3459fb345ccd1a22742728b951859c248e628e0b1b968968ad00f025ea070173816fb476

data/LICENSE

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © `<2024>` `<Faveod>`
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,30 @@
+# Oppen's Pretty Printer
+[![CI badge]][CI]
+[![Docs latest badge]][Docs latest]
+<!-- [![rubygems.org badge]][rubygems.org] -->
+
+[CI badge]: https://github.com/Faveod/oppen-ruby/actions/workflows/test.yml/badge.svg
+[CI]: https://github.com/Faveod/oppen-ruby/actions/workflows/test.yml
+[Docs latest badge]: https://github.com/Faveod/oppen-ruby/actions/workflows/docs.yml/badge.svg
+[Docs latest]: https://faveod.github.io/oppen-ruby/
+
+An implementation of the pretty printing algorithm described by
+[Derek C. Oppen](https://dl.acm.org/doi/pdf/10.1145/357114.357115).
+
+> [!WARNING]
+> This is still under development.
+
+## Difference with the original algorithm
+
+We decided to diverge from Oppen's original algorithm to provide a more
+idiomatic Ruby experience, in one particular aspect: exceptions/errors: 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.
+
+## Related projects
+
+1. [Python implementation](https://github.com/stevej2608/oppen-pretty-printer)
+as a library.
+1. [rustc implementation](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast_pretty/pp/index.html)

data/bin/main.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) if !$LOAD_PATH.include?(lib)
+
+require 'oppen'
+
+list = [
+  Oppen::Token::Begin.new,
+  Oppen::Token::String.new('XXXXXXXXXX'),
+  Oppen::Token::Break.new,
+  Oppen::Token::String.new('+'),
+  Oppen::Token::Break.new,
+  Oppen::Token::String.new('YYYYYYYYYY'),
+  Oppen::Token::Break.new,
+  Oppen::Token::String.new('+'),
+  Oppen::Token::Break.new,
+  Oppen::Token::String.new('ZZZZZZZZZZ'),
+  Oppen::Token::End.new,
+  Oppen::Token::EOF.new,
+]
+
+puts Oppen.print tokens: list, line_width: 25

data/bin/repl.rb

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

data/lib/oppen/print_stack.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+# Oppen.
+module Oppen
+  # Class that represents a stack that builds an output string
+  # using the values of the tokens that were pushed into it.
+  class PrintStack
+    # Class that represents an item in the print stack.
+    class PrintStackEntry
+      # @return [Integer] Indentation level.
+      attr_reader :offset
+      # @return [Token::BreakType] (Called break in the original paper).
+      attr_reader :break_type
+
+      def initialize(offset, break_type)
+        @offset = offset
+        @break_type = break_type
+      end
+    end
+
+    # IO element that builds the output.
+    attr_reader :buffer
+
+    # Array representing the stack of PrintStackEntries.
+    attr_reader :items
+
+    # Delimiter between lines in output
+    attr_reader :new_line
+
+    # Page margin (Called length in the original paper).
+    attr_reader :margin
+
+    # Current available space (Called index in the original paper).
+    #
+    # @return [Integer] Current available space (Called index in the original paper).
+    attr_reader :space
+
+    def initialize(margin, new_line)
+      @buffer = StringIO.new
+      @items = []
+      @new_line = new_line
+      @margin = margin
+      @space = margin
+    end
+
+    # Returns the output of the print stack
+    #
+    # @return [StringIO]
+    def output
+      buffer.string
+    end
+
+    # Core method responsible for building the print stack and the output string.
+    #
+    # @note Called Print in the original paper.
+    #
+    # @param token [Token]
+    # @param token_length [Integer]
+    #
+    # @return [Nil]
+    def print(token, token_length)
+      case token
+      in Token::Begin
+        handle_begin token, token_length
+      in Token::End
+        handle_end
+      in Token::Break
+        handle_break token, token_length
+      in Token::String
+        handle_string token, token_length
+      end
+    end
+
+    # Handle Begin Token.
+    #
+    # @param token [Token]
+    # @param token_length [Integer]
+    #
+    # @return [Nil]
+    #
+    # @see Token::Begin
+    def handle_begin(token, token_length)
+      if token_length > space
+        type =
+          if token.break_type == Token::BreakType::CONSISTENT
+            Token::BreakType::CONSISTENT
+          else
+            Token::BreakType::INCONSISTENT
+          end
+        push PrintStackEntry.new space - token.offset, type
+      else
+        push PrintStackEntry.new 0, Token::BreakType::FITS
+      end
+    end
+
+    # Handle End Token.
+    #
+    # @return [Nil]
+    #
+    # @see Token::End
+    def handle_end
+      pop
+    end
+
+    # Handle Break Token.
+    #
+    # @param token [Token]
+    # @param token_length [Integer]
+    #
+    # @return [Nil]
+    #
+    # @see Token::Break
+    def handle_break(token, token_length)
+      block = top
+      case block.break_type
+      in Token::BreakType::FITS
+        @space -= token.blank_space
+        indent token.blank_space
+      in Token::BreakType::CONSISTENT
+        @space = block.offset - token.offset
+        print_new_line margin - space
+      in Token::BreakType::INCONSISTENT
+        if token_length > space
+          @space = block.offset - token.offset
+          print_new_line margin - space
+        else
+          @space -= token.blank_space
+          indent token.blank_space
+        end
+      end
+    end
+
+    # Handle String Token.
+    #
+    # @param token [Token]
+    # @param token_length [Integer]
+    #
+    # @return [Nil]
+    #
+    # @see Token::String
+    def handle_string(token, token_length)
+      @space = [0, space - token_length].max
+      write token.value
+    end
+
+    # Push a PrintStackEntry into the stack.
+    #
+    # @param print_stack_entry [PrintStackEntry]
+    #
+    # @return [Nil]
+    def push(print_stack_entry)
+      items.append(print_stack_entry)
+    end
+
+    # Pop a PrintStackEntry from the stack.
+    #
+    # @return [PrintStackEntry]
+    def pop
+      if items.empty?
+        raise 'Popping empty stack'
+      end
+
+      items.pop
+    end
+
+    # Get the element at the top of the stack.
+    #
+    # @return [PrintStackEntry]
+    def top
+      if items.empty?
+        raise 'Accessing empty stack'
+      end
+
+      items.last
+    end
+
+    # Add a new line to the output.
+    #
+    # @note Called PrintNewLine as well in the original paper.
+    #
+    # @param amount [Integer] indentation amount.
+    #
+    # @return [Nil]
+    def print_new_line(amount)
+      write new_line
+      indent amount
+    end
+
+    # Write a string to the output.
+    #
+    # @param string [String]
+    #
+    # @return [Nil]
+    def write(string)
+      buffer.write(string)
+    end
+
+    # Add indentation by `amount`.
+    #
+    # @note Called Indent as well in the original paper.
+    #
+    # @param amount [Integer]
+    #
+    # @return [Nil]
+    def indent(amount)
+      write ' ' * amount
+    end
+  end
+end

data/lib/oppen/printer.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+require_relative 'scan_stack'
+require_relative 'print_stack'
+
+# Oppen.
+module Oppen
+  # Oppen pretty-printer.
+  class Printer
+    # Ring buffer left index.
+    #
+    # @note Called left as well in the original paper.
+    attr_reader :left
+
+    # Total number of spaces needed to print from start of buffer to the left.
+    #
+    # @note Called leftTotal as well in the original paper.
+    attr_reader :left_total
+
+    # @note Called printStack as well in the original paper.
+    attr_reader :print_stack
+
+    # Ring buffer right index.
+    #
+    # @note Called right as well in the original paper.
+    attr_reader :right
+
+    # Total number of spaces needed to print from start of buffer to the right.
+    #
+    # @note Called leftTotal as well in the original paper.
+    attr_reader :right_total
+
+    # Potential breaking positions.
+    #
+    # @note Called scanStack as well in the original paper.
+    attr_reader :scan_stack
+
+    # Size buffer, initially filled with nil.
+    #
+    # @note Called size as well in the original paper.
+    attr_reader :size
+
+    # Token buffer, initially filled with nil.
+    #
+    # @note Called token in the original paper.
+    attr_reader :tokens
+
+    # @note Called PrettyPrintInit in the original paper.
+    #
+    # @param margin   [Integer] maximum line width desired.
+    # @param new_line [String]  the delimiter between lines.
+    def initialize(margin, new_line)
+      # Maximum size if the stacks
+      n = 3 * margin
+
+      @left = 0
+      @left_total = 1
+      @print_stack = PrintStack.new margin, new_line
+      @right = 0
+      @right_total = 1
+      @scan_stack = ScanStack.new n
+      @size = Array.new n
+      @tokens = Array.new n
+    end
+
+    # @return [StringIO]
+    def output
+      print_stack.output
+    end
+
+    # Core function of the algorithm responsible for populating the scan and print stack.
+    #
+    # @note Called PrettyPrint as well in the original paper.
+    #
+    # @param token [Token]
+    #
+    # @return [Nil]
+    def print(token)
+      case token
+      in Token::EOF
+        handle_eof
+      in Token::Begin
+        handle_begin token
+      in Token::End
+        handle_end token
+      in Token::Break
+        handle_break token
+      in Token::String
+        handle_string token
+      end
+    end
+
+    # Handle EOF Token.
+    #
+    # @return [Nil]
+    #
+    # @see Token::EOF
+    def handle_eof
+      if !scan_stack.empty?
+        check_stack 0
+        advance_left tokens[left], size[left]
+      end
+      print_stack.indent 0
+    end
+
+    # Handle Begin Token.
+    #
+    # @return [Nil]
+    #
+    # @see Token::Begin
+    def handle_begin(token)
+      if scan_stack.empty?
+        @left = 0
+        @left_total = 1
+        @right = 0
+        @right_total = 1
+      else
+        advance_right
+      end
+      tokens[right] = token
+      size[right] = -right_total
+      scan_stack.push right
+    end
+
+    # Handle End Token.
+    #
+    # @return [Nil]
+    #
+    # @see Token::End
+    def handle_end(token)
+      if scan_stack.empty?
+        print_stack.print token, 0
+      else
+        advance_right
+        tokens[right] = token
+        size[right] = -1
+        scan_stack.push right
+      end
+    end
+
+    # Handle Break Token.
+    #
+    # @return [Nil]
+    #
+    # @see Token::Break
+    def handle_break(token)
+      if scan_stack.empty?
+        @left = 0
+        @left_total = 1
+        @right = 0
+        @right_total = 1
+      else
+        advance_right
+      end
+      check_stack 0
+      scan_stack.push right
+      tokens[right] = token
+      size[right] = -right_total
+      @right_total += token.blank_space
+    end
+
+    # Handle String Token.
+    #
+    # @return [Nil]
+    #
+    # @see Token::String
+    def handle_string(token)
+      if scan_stack.empty?
+        print_stack.print token, token.length
+      else
+        advance_right
+        tokens[right] = token
+        size[right] = token.length
+        @right_total += token.length
+        check_stream
+      end
+    end
+
+    # Flushes the input if possible.
+    #
+    # @note Called CheckStream as well in the original paper.
+    #
+    # @return [Nil]
+    def check_stream
+      return if right_total - left_total <= print_stack.space
+
+      if !scan_stack.empty? && left == scan_stack.bottom
+        size[scan_stack.pop_bottom] = Float::INFINITY
+      end
+      advance_left tokens[left], size[left]
+      return if left == right
+
+      check_stream
+    end
+
+    # Advances the `right` pointer.
+    #
+    # @note Called AdvanceRight as well in the original paper.
+    #
+    # @return [Nil]
+    def advance_right
+      @right = (right + 1) % scan_stack.length
+      return if right != left
+
+      raise 'Token queue full'
+    end
+
+    # 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.
+    #
+    # @return [Nil]
+    def advance_left(token, token_length)
+      return if token_length.negative?
+
+      print_stack.print token, token_length
+
+      case token
+      when Token::Break
+        @left_total += token.blank_space
+      when Token::String
+        @left_total += token_length
+      end
+
+      return if left == right
+
+      @left = (left + 1) % scan_stack.length
+      advance_left tokens[left], size[left]
+    end
+
+    # Updates the size buffer taking into
+    # account the length of the current group.
+    #
+    # @note Called CheckStack as well in the original paper.
+    #
+    # @param depth [Integer] depth of the group
+    #
+    # @return [Nil]
+    def check_stack(depth) # rubocop:disable Metrics/AbcSize
+      return if scan_stack.empty?
+
+      x = scan_stack.top
+      case tokens[x]
+      when Token::Begin
+        if depth.positive?
+          size[scan_stack.pop] = size[x] + right_total
+          check_stack depth - 1
+        end
+      when Token::End
+        size[scan_stack.pop] = 1
+        check_stack depth + 1
+      else
+        size[scan_stack.pop] = size[x] + right_total
+        if depth.positive?
+          check_stack depth
+        end
+      end
+    end
+  end
+end

data/lib/oppen/scan_stack.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# Oppen.
+module Oppen
+  # A fixed-size stack that can be popped from top and bottom.
+  class ScanStack
+    def initialize(size)
+      @bottom = 0
+      @empty = true
+      @stack = Array.new(size)
+      @top = 0
+    end
+
+    # @return [Boolean]
+    def empty?
+      @empty
+    end
+
+    # @return [Integer]
+    def length
+      @stack.length
+    end
+
+    # @return [Object]
+    def top
+      if empty?
+        raise 'Accessing empty stack from top'
+      end
+
+      @stack[@top]
+    end
+
+    # @return [Object]
+    def bottom
+      if empty?
+        raise 'Accessing empty stack from bottom'
+      end
+
+      @stack[@bottom]
+    end
+
+    # Increment index (no overflow).
+    #
+    # @param index [Integer]
+    #
+    # @return [Integer]
+    def increment(index)
+      (index + 1) % length
+    end
+
+    # Decrement index (no overflow).
+    #
+    # @param index [Integer]
+    #
+    # @return [Integer]
+    def decrement(index)
+      (index - 1) % length
+    end
+
+    # Push a value to the top.
+    #
+    # @param value [Object]
+    #
+    # @return [Nil]
+    def push(value)
+      if empty?
+        @empty = false
+      else
+        @top = increment(@top)
+        if @top == @bottom
+          raise 'Stack full'
+        end
+      end
+      @stack[@top] = value
+    end
+
+    # Pop a value from the top.
+    #
+    # @return [Nil]
+    def pop
+      if empty?
+        raise 'Popping empty stack from top'
+      end
+
+      res = top
+      if @top == @bottom
+        @empty = true
+      else
+        @top = decrement(@top)
+      end
+      res
+    end
+
+    # Pop a value from the bottom.
+    #
+    # @return [Nil]
+    def pop_bottom
+      if empty?
+        raise 'Popping empty stack from bottom'
+      end
+
+      res = bottom
+      if @top == @bottom
+        @empty = true
+      else
+        @bottom = increment(@bottom)
+      end
+      res
+    end
+  end
+end

data/lib/oppen/token.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Oppen.
+module Oppen
+  # Token.
+  module Token
+    # BreakType.
+    #
+    # 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
+
+    # String Token.
+    class String
+      # @return [String] String value.
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      # @return [Integer]
+      def length
+        value.length
+      end
+    end
+
+    # Break Token.
+    class Break
+      # @return [Integer] Number of blank spaces.
+      attr_reader :blank_space
+      # @return [Integer] Indentation.
+      attr_reader :offset
+
+      def initialize(blank_space: 1, offset: 0)
+        @blank_space = blank_space
+        @offset = offset
+      end
+    end
+
+    # Distinguished instance of Break which forces a line break.
+    class LineBreak < Break
+      def initialize(offset: 0)
+        super(blank_space: 9999, offset:)
+      end
+    end
+
+    # Begin Token.
+    class Begin
+      # @return [BreakType]
+      attr_reader :break_type
+      # @return [Integer] Indentation.
+      attr_reader :offset
+
+      def initialize(break_type: BreakType::INCONSISTENT, offset: 2)
+        @offset = offset
+        @break_type = break_type
+      end
+    end
+
+    # End Token
+    class End
+      nil
+    end
+
+    # EOF Token
+    class EOF
+      nil
+    end
+  end
+end

data/lib/oppen/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Oppen.
+module Oppen
+  # Oppen version
+  #
+  # @return [String] current version
+  VERSION = '0.1.0' # managed by release.sh
+end

data/lib/oppen.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'oppen/printer'
+require_relative 'oppen/print_stack'
+require_relative 'oppen/scan_stack'
+require_relative 'oppen/token'
+require_relative 'oppen/version'
+
+# Oppen.
+module Oppen
+  # Entry point of the pretty printer.
+  #
+  # @param tokens [Array[Token]] the list of tokens to be printed
+  # @param margin [Integer] maximum line width desired
+  # @param new_line [String] the delimiter between lines
+  #
+  # @return [StringIO] output of the pretty printer
+  def self.print(tokens: [], margin: 80, new_line: "\n")
+    printer = Printer.new margin, new_line
+    tokens.each do |token|
+      printer.print token
+    end
+    printer.output
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: oppen
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Amine Mike El Maalouf <amine.el-maalouf@epita.fr>
+- Firas al-Khalil <firasalkhalil@gmail.com>
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-09-13 00:00:00.000000000 Z
+dependencies: []
+description: Implementation of the Oppen's pretty printing algorithm
+email: 
+executables:
+- main.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/main.rb
+- bin/repl.rb
+- lib/oppen.rb
+- lib/oppen/print_stack.rb
+- lib/oppen/printer.rb
+- lib/oppen/scan_stack.rb
+- lib/oppen/token.rb
+- lib/oppen/version.rb
+homepage: http://github.com/Faveod/oppen-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key: 
+specification_version: 4
+summary: Pretty-printing library
+test_files: []