marktable 0.0.5 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3e8c1a76daf4c3d03f628200baabad28e31008e444522fb2d6c7337f623bdd8
-  data.tar.gz: c83d7b0a83b21c2c292d5a76963f626ddeae5bebca42363f227f6bf65fed6dc2
+  metadata.gz: f4dc7dda731d7cbac0c2b155c3c572c44954ca2f65281f3cf976b05ba9cd1532
+  data.tar.gz: 1261f5a0afd0bbf45a16d8e9d369ef61b8e9313e83788a1b5e10be8871fac962
 SHA512:
-  metadata.gz: f0f766d34db37402b6d4cbb52e37a1e33172175c5ba622051ce9899ded65de3c9fa045f7d21a234c9fc03856bfaefcf7b9b8d5f1fb346bd0c47efbee87e86236
-  data.tar.gz: 1a34281c031a0c47da3ff074f6206304fc569663a04ffab9246bd12a137eb7fd53a6745415991d6530d384f67e05eca480db02bdd9c49122687a9ae820475037
+  metadata.gz: 8127ab236b08a55f8d8d2fafcb116996d347527085af2dc1e71632b55930d326eae6e6b8bbac2e55c33965effa4d14863b4741e80c70297b2079bf715153dab6
+  data.tar.gz: 8400c3fbb70a9330d2db6c36f23599161ae35e4766c614597f773f38305ae9bf62708d053477d5e727d7cf51dee76490bb23743c0c77aca76a4a87997795e9be

data/README.md

@@ -1,8 +1,27 @@
 # Marktable
 
-Marktable is a Ruby gem for ...
 
-## Installation
+A powerful Ruby library for parsing, manipulating, and generating Markdown tables with an elegant and intuitive API.
+
+## 📚 Overview
+
+Marktable allows you to seamlessly work with Markdown tables using familiar Ruby data structures. Whether you're parsing tables from Markdown documents, generating tables for documentation, or manipulating tabular data, Marktable provides simple yet powerful tools for all your Markdown table needs.
+
+## ✨ Features
+
+- **Custom RSpec matcher** for testing Markdown-like data structures (including html tables) against expected Markdown output
+- **Parse** Markdown tables into Ruby data structures (arrays or hashes)
+- **Generate** beautifully formatted Markdown tables from Ruby objects
+- **Filter** and **transform** table data with Ruby's familiar block syntax
+- **Auto-detect** headers from properly formatted Markdown tables
+- **Handle** tables with or without headers
+- **Support** for mismatched columns and keys in data
+- **Convert** between array-based and hash-based representations
+
+## Not supported
+- Non-string values (E.g. complex objects) in the table rows. 
+
+## 📦 Installation
 
 Add this line to your application's Gemfile:
 
@@ -22,13 +41,333 @@ Or install it yourself as:
 gem install marktable
 ```
 
-## Usage
+## 🚀 Quick Start
+
+### Main use case (Rspec only at this time)
+
+This gem started as a pet project aiming at:
+- Simplifying the process of testing html table content
+- Making these specs more developer-friendly, with a very readable format
+
+
+```ruby
+visit my_path
+actual_table = page.find('#my-table')
+expected_table = <<~MARKDOWN
+  | Name  | Age | City     |
+  | ----- | --- | -------- |
+  | John  | 30  | New York |
+  | Jane  | 25  | Boston   |
+  | Bob   | 17  | Chicago  |
+MARKDOWN
+
+expect(actual_table).to match_markdown(expected_table)
+```
+
+In case of semantical mismatch, the matcher will show an easy to verify markdown representation of the tables:
+
+```markdown
+        Expected markdown table to match:
+        
+        Expected:
+        | Name  | Age | City     |
+        | ----- | --- | -------- |
+        | John  | 30  | New York |
+        | Jane  | 25  | Boston   |
+        | Bob   | 17  | Chicago  |
+        
+        Actual:
+        | Name | Age |
+        | ---- | --- |
+        | John | 31  |
+        | Jane | 25  |
+        
+        Parsed expected data: [{"Name" => "John", "Age" => "30"}, {"Name" => "Jane", "Age" => "25"}, {"Name" => "Bob", "Age" => "17"}]
+        Parsed actual data: [{"Name" => "John", "Age" => "31"}, {"Name" => "Jane", "Age" => "25"}]
+```
+
+
+
+### Parsing a Markdown Table
 
 ```ruby
 require 'marktable'
-# Example usage here
+
+markdown_table = <<~MARKDOWN
+  | Name  | Age | City     |
+  | ----- | --- | -------- |
+  | John  | 30  | New York |
+  | Jane  | 25  | Boston   |
+MARKDOWN
+
+# Parse into an array of hashes (with auto-detected headers)
+data = Marktable.parse(markdown_table)
+# => [
+#      {"Name"=>"John", "Age"=>"30", "City"=>"New York"},
+#      {"Name"=>"Jane", "Age"=>"25", "City"=>"Boston"}
+#    ]
+
+# Access data easily
+puts data.first["Name"]  # => "John"
+```
+
+### Generating a Markdown Table
+
+```ruby
+# Create a new table and add rows
+table = Marktable.generate do |t|
+  t << {"Name" => "John", "Age" => "30", "City" => "New York"}
+  t << {"Name" => "Jane", "Age" => "25", "City" => "Boston"}
+  t << {"Name" => "Bob", "Age" => "17", "City" => "Chicago"}
+end
+
+puts table
+# | Name | Age | City     |
+# | ---- | --- | -------- |
+# | John | 30  | New York |
+# | Jane | 25  | Boston   |
+# | Bob  | 17  | Chicago  |
+```
+
+## 📖 Usage Guide
+
+### Working with Table Objects
+
+Create a table object for more advanced operations:
+
+```ruby
+# Create from a markdown string
+table = Marktable.new(markdown_table)
+
+# Or create from array data
+array_data = [
+  ["Name", "Age", "City"],
+  ["John", "30", "New York"],
+  ["Jane", "25", "Boston"],
+  ["Bob", "17", "Chicago"]
+]
+table = Marktable.new(array_data, headers: true)
+
+# Or with auto-detected headers
+array_data = [
+  { "Name" => "John", "Age" => "30", "City" => "New York" },
+  { "Name" => "Jane", "Age" => "25", "City" => "Boston" },
+  { "Name" => "Bob", "Age" => "17", "City" => "Chicago" }
+]
+table = Marktable.new(array_data)
+```
+
+### Filtering Rows
+
+Filter rows using pattern matching or blocks:
+
+```ruby
+# Filter with a regex pattern
+nyc_residents = table.filter(/New York/)
+
+# Filter with a block
+adults = table.filter do |row|
+  row["Age"].to_i >= 18
+end
+
+puts adults
+# | Name | Age | City     |
+# | ---- | --- | -------- |
+# | John | 30  | New York |
+# | Jane | 25  | Boston   |
+```
+
+### Transforming Data
+
+Transform table data with the map method:
+
+```ruby
+# Add 5 years to everyone's age
+older = table.map do |row|
+  row.merge("Age" => (row["Age"].to_i + 5).to_s)
+end
+
+puts older
+# | Name | Age | City     |
+# | ---- | --- | -------- |
+# | John | 35  | New York |
+# | Jane | 30  | Boston   |
+# | Bob  | 22  | Chicago  |
+```
+
+### Working with Arrays
+
+Use arrays instead of hashes for row data:
+
+```ruby
+# Create a table with array rows
+table = Marktable.new([], headers: false)
+table << ["John", "30", "New York"]
+table << ["Jane", "25", "Boston"]
+
+puts table
+# | John | 30  | New York |
+# | Jane | 25  | Boston   |
+```
+
+### Mixed Row Types
+
+Marktable can handle mixed row types (arrays and hashes):
+
+```ruby
+table = Marktable.generate do |t|
+  t << {"Name" => "John", "Age" => "30", "City" => "New York"}
+  t << ["Jane", "25", "Boston"]  # Array with same column count
+end
+
+puts table
+# | Name | Age | City     |
+# | ---- | --- | -------- |
+# | John | 30  | New York |
+# | Jane | 25  | Boston   |
+```
+
+## 🧪 Testing with Custom Matchers
+
+Marktable includes a custom RSpec matcher, `match_markdown`, to make testing Markdown-compatible data structures simple and reliable.
+
+### Using the `match_markdown` Matcher
+
+First, require the matcher in your spec_helper.rb or in the specific test file:
+
+```ruby
+require 'marktable/rspec'
+```
+
+#### Testing Markdown Table Output
+
+```ruby
+RSpec.describe ReportGenerator do
+  describe "#generate_customer_table" do
+    it "generates the expected customer table" do
+      actual = ReportGenerator.new(customers).generate_table
+      # Presume actual contains:
+      # [
+      #   { id: 1, name: "John Smith", status: "Active" },
+      #   { id: 2, name: "Jane Doe", status: "Pending" }
+      # ]
+      
+      expected = <<~MARKDOWN
+        | ID | Name       | Status  |
+        | -- | ---------- | ------- |
+        | 1  | John Smith | Active  |
+        | 2  | Jane Doe   | Pending |
+      MARKDOWN
+      
+      expect(result).to match_markdown(expected)
+    end
+  end
+end
 ```
 
-## Development
+#### Testing HTML Table Output
+
+The `match_markdown` matcher can also compare HTML tables by extracting their semantic content:
+
+```ruby
+RSpec.describe HtmlReportGenerator do
+  describe "#generate_sales_report" do
+    it "generates the expected HTML table" do
+      sales_data = [
+        { product: "Widget A", quantity: 150, revenue: "$3,000" },
+        { product: "Widget B", quantity: 75, revenue: "$1,875" }
+      ]
+      
+      generator = HtmlReportGenerator.new(sales_data)
+      html_output = generator.generate_sales_report
+      
+      # The matcher extracts the data structure from both the HTML and expected markdown
+      expected = <<~MARKDOWN
+        | Product  | Quantity | Revenue |
+        | -------- | -------- | ------- |
+        | Widget A | 150      | $3,000  |
+        | Widget B | 75       | $1,875  |
+      MARKDOWN
+      
+      # This will pass even though one is HTML and one is Markdown!
+      expect(html_output).to match_markdown(expected)
+    end
+  end
+end
+```
+
+#### Testing API JSON Responses
+
+The matcher is also helpful when testing APIs that return tabular data:
+
+```ruby
+RSpec.describe "Products API" do
+  describe "GET /api/products" do
+    it "returns products in the expected format" do
+      # Setup test data and make request
+      get "/api/products"
+      
+      # Parse JSON response
+      json_response = JSON.parse(response.body)
+      
+      # Convert API response to a table
+      table = Marktable.new(json_response)
+      
+      expected = <<~MARKDOWN
+        | id | name        | category | price  |
+        | -- | ----------- | -------- | ------ |
+        | 1  | Product One | Books    | $19.99 |
+        | 2  | Product Two | Games    | $59.99 |
+      MARKDOWN
+      
+      expect(table).to match_markdown(expected)
+    end
+  end
+end
+```
+
+The `match_markdown` matcher compares tables semantically rather than character-by-character, which means:
+
+- It ignores differences in whitespace padding
+- It handles different column ordering in hash-based tables
+- It works with both HTML and Markdown table formats
+- It provides clear error messages showing the differences between tables
+
+## 📋 API Reference
+
+### Class Methods
+
+- `Marktable.parse(table, headers: nil)` - Parse table string or array into an array of hashes/arrays
+- `Marktable.new(table, headers: nil)` - Create a new Table object
+- `Marktable.parse_line(row)` - Parse a single markdown row into an array
+- `Marktable.generate { |t| ... }` - Generate a table with a block
+
+### Instance Methods
+
+- `table.to_a` - Convert table to array of hashes/arrays
+- `table.to_s` / `table.generate` - Generate markdown representation
+- `table.empty?` - Check if table is empty
+- `table.column_count` - Get column count
+- `table << row_data` - Add a row to the table
+- `table.filter(pattern = nil) { |row| ... }` - Filter rows by pattern or block
+- `table.map { |row| ... }` - Transform rows with a block
+
+## 🧪 Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/marktable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/yourusername/marktable/blob/main/CODE_OF_CONDUCT.md).
+
+1. Fork the repository
+2. Create your feature branch: `git checkout -b my-new-feature`
+3. Commit your changes: `git commit -am 'Add some feature'`
+4. Push to the branch: `git push origin my-new-feature`
+5. Submit a pull request
+
+## 📄 License
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/marktable/formatters/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'markdown'
+# require_relative "array"
+require_relative 'csv'
+require_relative 'html'
+
+module Marktable
+  module Formatters
+    class Base
+      def self.for(type)
+        case type.to_sym
+        when :markdown
+          Markdown
+        when :array
+          Array
+        when :csv
+          CSV
+        when :html
+          HTML
+        else
+          raise ArgumentError, "Unknown table type: #{type}"
+        end
+      end
+    end
+  end
+end

data/lib/marktable/formatters/csv.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'csv'
+
+module Marktable
+  module Formatters
+    class CSV
+      def self.format(rows, headers = nil)
+        return '' if rows.empty? && headers.nil?
+
+        ::CSV.generate do |csv|
+          csv << headers if headers
+          rows.each do |row|
+            csv << format_row(row)
+          end
+        end
+      end
+
+      def self.format_row(row)
+        row.values.map { |val| val unless val.to_s.empty? }
+      end
+    end
+  end
+end

data/lib/marktable/formatters/html.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module Marktable
+  module Formatters
+    class HTML
+      def self.format(rows, headers = nil)
+        return '' if rows.empty? && headers.nil?
+
+        builder = Nokogiri::HTML::Builder.new do |doc|
+          doc.table do
+            if headers
+              doc.thead do
+                doc.tr do
+                  headers.each do |header|
+                    doc.th { doc.text header }
+                  end
+                end
+              end
+            end
+
+            doc.tbody do
+              rows.each do |row|
+                doc.tr do
+                  row.each_value do |cell|
+                    doc.td do
+                      cell_text = cell.to_s
+                      if cell_text.include?('\n')
+                        cell_text.split('\n').each_with_index do |line, index|
+                          doc.br if index.positive?
+                          doc.text line
+                        end
+                      else
+                        doc.text cell_text
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        # Extract just the table element to avoid including DOCTYPE
+        builder.doc.at_css('table').to_html
+      end
+    end
+  end
+end

data/lib/marktable/formatters/markdown.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Marktable
+  module Formatters
+    class Markdown
+      def self.format(rows, headers = nil)
+        return '' if rows.empty? && headers.nil?
+
+        # Calculate column widths
+        widths = calculate_column_widths(rows, headers)
+
+        lines = []
+
+        # Add header row if we have headers
+        if headers
+          lines << Row.new(headers).to_markdown(widths)
+          lines << separator_row(widths)
+        end
+
+        # Add data rows
+        rows.each do |row|
+          lines << row.to_markdown(widths)
+        end
+
+        lines.join("\n")
+      end
+
+      def self.calculate_column_widths(rows, headers)
+        # Determine the maximum number of columns to consider
+        max_cols = headers ? headers.size : 0
+
+        if headers.nil?
+          # Without headers, find the maximum number of values across all rows
+          rows.each do |row|
+            max_cols = [max_cols, row.values.size].max
+          end
+        end
+
+        # Initialize widths array with zeros
+        widths = Array.new(max_cols, 0)
+
+        # Process headers if available
+        headers&.each_with_index do |header, i|
+          width = header.to_s.length
+          widths[i] = width if width > widths[i]
+        end
+
+        # Process row values, but only up to the max_cols
+        rows.each do |row|
+          values = row.values.take(max_cols)
+          values.each_with_index do |value, i|
+            width = value.to_s.length
+            widths[i] = width if width > widths[i]
+          end
+        end
+
+        widths
+      end
+
+      def self.separator_row(widths)
+        separator_parts = widths.map { |width| '-' * width }
+        "| #{separator_parts.join(' | ')} |"
+      end
+    end
+  end
+end