notare 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 913db4066f434c9f4fa4dda05b007642c08a08e44aecaaf105d12e77c7ab724e
+  data.tar.gz: 013f0cb3ce077237d040583a8ea39ce1718b0db7ff5b9b8ff89954e4a6386c3f
+SHA512:
+  metadata.gz: b078513721fac08090157247172d5e4ce06cbb0d10770d07169e630a147a9cef688180544c550ec0e441e6cbadbcc810dffcb51029de2c61b0a4c577af80442f
+  data.tar.gz: 80af9a1ea5e9d585b41d516b3c49418d28f7fe8314549958d420109b24d402f0e7fdd57e9536fa350665e1d5da310a6ed8497425f0b8b291d95fd606f87abdd2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mathias
+
+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,323 @@
+# Notare
+
+A Ruby gem for creating docx files with a simple DSL
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'notare'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install notare
+
+## Usage
+
+### Basic Example
+
+```ruby
+require 'notare'
+
+Notare::Document.create("output.docx") do |doc|
+  doc.p "Hello World"
+end
+```
+
+### Paragraphs
+
+```ruby
+Notare::Document.create("output.docx") do |doc|
+  # Simple paragraph
+  doc.p "This is a paragraph."
+
+  # Paragraph with multiple text runs
+  doc.p do
+    doc.text "First part. "
+    doc.text "Second part."
+  end
+end
+```
+
+### Text Formatting
+
+Formatting uses nested blocks. Nesting combines formatting styles.
+
+```ruby
+Notare::Document.create("output.docx") do |doc|
+  doc.p do
+    doc.text "Normal text "
+    doc.b { doc.text "bold" }
+    doc.text " and "
+    doc.i { doc.text "italic" }
+    doc.text " and "
+    doc.u { doc.text "underlined" }
+  end
+
+  # Nested formatting (bold + italic)
+  doc.p do
+    doc.b do
+      doc.i { doc.text "bold and italic" }
+    end
+  end
+end
+```
+
+### Headings
+
+Use `h1` through `h6` for document headings:
+
+```ruby
+Notare::Document.create("output.docx") do |doc|
+  doc.h1 "Document Title"
+  doc.h2 "Chapter 1"
+  doc.h3 "Section 1.1"
+  doc.h4 "Subsection"
+  doc.h5 "Minor heading"
+  doc.h6 "Smallest heading"
+
+  # Headings with formatted content
+  doc.h2 do
+    doc.text "Chapter with "
+    doc.i { doc.text "emphasis" }
+  end
+end
+```
+
+### Styles
+
+Notare includes built-in styles and supports custom style definitions.
+
+#### Built-in Styles
+
+```ruby
+Notare::Document.create("output.docx") do |doc|
+  doc.p "This is a title", style: :title
+  doc.p "A subtitle", style: :subtitle
+  doc.p "A quotation", style: :quote
+  doc.p "puts 'code'", style: :code
+end
+```
+
+#### Custom Styles
+
+Define your own styles with text and paragraph properties:
+
+```ruby
+Notare::Document.create("output.docx") do |doc|
+  # Define custom styles
+  doc.define_style :warning,
+    bold: true,
+    color: "FF0000",
+    size: 14
+
+  doc.define_style :note,
+    italic: true,
+    color: "0066CC",
+    font: "Georgia"
+
+  doc.define_style :centered,
+    align: :center,
+    size: 12
+
+  # Apply to paragraphs
+  doc.p "Warning message!", style: :warning
+  doc.p "Centered text", style: :centered
+
+  # Apply to text runs
+  doc.p do
+    doc.text "Normal text, "
+    doc.text "important!", style: :warning
+    doc.text ", and "
+    doc.text "a note", style: :note
+  end
+end
+```
+
+#### Style Properties
+
+**Text properties:**
+- `bold: true/false`
+- `italic: true/false`
+- `underline: true/false`
+- `color: "FF0000"` (hex RGB)
+- `size: 14` (points)
+- `font: "Arial"` (font family)
+
+**Paragraph properties:**
+- `align: :left / :center / :right / :justify`
+- `indent: 720` (twips, 1 inch = 1440 twips)
+- `spacing_before: 240` (twips)
+- `spacing_after: 240` (twips)
+
+### Lists
+
+#### Bullet Lists
+
+```ruby
+Notare::Document.create("output.docx") do |doc|
+  doc.ul do
+    doc.li "First item"
+    doc.li "Second item"
+    doc.li { doc.b { doc.text "Bold item" } }
+  end
+end
+```
+
+#### Numbered Lists
+
+```ruby
+Notare::Document.create("output.docx") do |doc|
+  doc.ol do
+    doc.li "First"
+    doc.li "Second"
+    doc.li "Third"
+  end
+end
+```
+
+### Tables
+
+```ruby
+Notare::Document.create("output.docx") do |doc|
+  doc.table do
+    doc.tr do
+      doc.td "Header 1"
+      doc.td "Header 2"
+    end
+    doc.tr do
+      doc.td "Cell 1"
+      doc.td { doc.b { doc.text "Bold cell" } }
+    end
+  end
+end
+```
+
+### Images
+
+Images can be added to paragraphs, table cells, and list items. Supports PNG and JPEG formats.
+
+```ruby
+Notare::Document.create("output.docx") do |doc|
+  # Simple image (uses native dimensions)
+  doc.p do
+    doc.image "photo.png"
+  end
+
+  # Image with explicit dimensions (inches, cm, or pixels)
+  doc.p do
+    doc.image "logo.png", width: "2in", height: "1in"
+  end
+
+  # Specify only width (height auto-calculated to maintain aspect ratio)
+  doc.p do
+    doc.image "banner.jpg", width: "5cm"
+  end
+
+  # Image with text in the same paragraph
+  doc.p do
+    doc.text "Company Logo: "
+    doc.image "logo.png", width: "0.5in", height: "0.5in"
+  end
+
+  # Image in a table cell
+  doc.table do
+    doc.tr do
+      doc.td "Product"
+      doc.td do
+        doc.image "product.jpg", width: "1in", height: "1in"
+      end
+    end
+  end
+
+  # Image in a list item
+  doc.ul do
+    doc.li do
+      doc.image "icon.png", width: "16px", height: "16px"
+      doc.text " List item with icon"
+    end
+  end
+end
+```
+
+### Complete Example
+
+```ruby
+Notare::Document.create("report.docx") do |doc|
+  doc.p "Monthly Report"
+
+  doc.p do
+    doc.text "This report contains "
+    doc.b { doc.text "important" }
+    doc.text " information."
+  end
+
+  doc.p "Key Points:"
+
+  doc.ul do
+    doc.li "Revenue increased by 15%"
+    doc.li "Customer satisfaction improved"
+    doc.li { doc.i { doc.text "See appendix for details" } }
+  end
+
+  doc.p "Summary Table:"
+
+  doc.table do
+    doc.tr do
+      doc.td "Metric"
+      doc.td "Value"
+    end
+    doc.tr do
+      doc.td "Revenue"
+      doc.td "$1.2M"
+    end
+    doc.tr do
+      doc.td "Growth"
+      doc.td { doc.b { doc.text "15%" } }
+    end
+  end
+end
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `p(text, style:)` | Create a paragraph with text and optional style |
+| `p(style:) { }` | Create a paragraph with block content and optional style |
+| `text(value, style:)` | Add text with optional style to the current context |
+| `h1(text)` - `h6(text)` | Create headings (level 1-6) |
+| `b { }` | Bold formatting |
+| `i { }` | Italic formatting |
+| `u { }` | Underline formatting |
+| `define_style(name, **props)` | Define a custom style |
+| `ul { }` | Bullet list |
+| `ol { }` | Numbered list |
+| `li(text)` | List item with text |
+| `li { }` | List item with block content |
+| `table { }` | Table |
+| `tr { }` | Table row |
+| `td(text)` | Table cell with text |
+| `td { }` | Table cell with block content |
+| `image(path, width:, height:)` | Insert image (PNG/JPEG). Dimensions: `"2in"`, `"5cm"`, `"100px"`, or integer pixels |
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests.
+
+```bash
+bundle install
+bundle exec rake test      # Run tests
+bundle exec rake rubocop   # Run linter
+bundle exec rake           # Run both
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/notare/builder.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Notare
+  module Builder
+    def p(text = nil, style: nil, &block)
+      para = Nodes::Paragraph.new(style: resolve_style(style))
+      if block
+        with_target(para, &block)
+      elsif text
+        para.add_run(Nodes::Run.new(text, **current_formatting))
+      end
+      @nodes << para
+    end
+
+    def text(value, style: nil)
+      formatting = current_formatting.merge(style: resolve_style(style))
+      @current_target.add_run(Nodes::Run.new(value, **formatting))
+    end
+
+    # Heading shortcuts
+    def h1(text = nil, &block)
+      p(text, style: :heading1, &block)
+    end
+
+    def h2(text = nil, &block)
+      p(text, style: :heading2, &block)
+    end
+
+    def h3(text = nil, &block)
+      p(text, style: :heading3, &block)
+    end
+
+    def h4(text = nil, &block)
+      p(text, style: :heading4, &block)
+    end
+
+    def h5(text = nil, &block)
+      p(text, style: :heading5, &block)
+    end
+
+    def h6(text = nil, &block)
+      p(text, style: :heading6, &block)
+    end
+
+    def image(path, width: nil, height: nil)
+      validate_image_path!(path)
+      img = register_image(path, width: width, height: height)
+      @current_target.add_run(img)
+    end
+
+    def b(&block)
+      with_format(:bold, &block)
+    end
+
+    def i(&block)
+      with_format(:italic, &block)
+    end
+
+    def u(&block)
+      with_format(:underline, &block)
+    end
+
+    def ul(&block)
+      list(:bullet, &block)
+    end
+
+    def ol(&block)
+      list(:number, &block)
+    end
+
+    def li(text = nil, &block)
+      item = Nodes::ListItem.new([], list_type: @current_list.type, num_id: @current_list.num_id)
+      if block
+        with_target(item, &block)
+      elsif text
+        item.add_run(Nodes::Run.new(text, **current_formatting))
+      end
+      @current_list.add_item(item)
+    end
+
+    def table(&block)
+      tbl = Nodes::Table.new
+      previous_table = @current_table
+      @current_table = tbl
+      block.call
+      @current_table = previous_table
+      @nodes << tbl
+    end
+
+    def tr(&block)
+      row = Nodes::TableRow.new
+      previous_row = @current_row
+      @current_row = row
+      block.call
+      @current_row = previous_row
+      @current_table.add_row(row)
+    end
+
+    def td(text = nil, &block)
+      cell = Nodes::TableCell.new
+      if block
+        with_target(cell, &block)
+      elsif text
+        cell.add_run(Nodes::Run.new(text, **current_formatting))
+      end
+      @current_row.add_cell(cell)
+    end
+
+    private
+
+    def list(type, &block)
+      @num_id_counter ||= 0
+      @num_id_counter += 1
+
+      list_node = Nodes::List.new(type: type, num_id: @num_id_counter)
+      previous_list = @current_list
+      @current_list = list_node
+      block.call
+      @current_list = previous_list
+      @nodes << list_node
+    end
+
+    def with_format(format, &block)
+      @format_stack ||= []
+      @format_stack.push(format)
+      block.call
+      @format_stack.pop
+    end
+
+    def with_target(target, &block)
+      previous_target = @current_target
+      @current_target = target
+      block.call
+      @current_target = previous_target
+    end
+
+    def current_formatting
+      @format_stack ||= []
+      {
+        bold: @format_stack.include?(:bold),
+        italic: @format_stack.include?(:italic),
+        underline: @format_stack.include?(:underline)
+      }
+    end
+
+    def validate_image_path!(path)
+      raise ArgumentError, "Image file not found: #{path}" unless File.exist?(path)
+
+      ext = File.extname(path).downcase
+      return if %w[.png .jpg .jpeg].include?(ext)
+
+      raise ArgumentError, "Unsupported image format: #{ext}. Use PNG or JPEG."
+    end
+
+    def resolve_style(style_or_name)
+      return nil if style_or_name.nil?
+      return style_or_name if style_or_name.is_a?(Style)
+
+      style(style_or_name) || raise(ArgumentError, "Unknown style: #{style_or_name}")
+    end
+  end
+end

data/lib/notare/document.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Notare
+  class Document
+    include Builder
+
+    attr_reader :nodes, :styles
+
+    def self.create(path, &block)
+      doc = new
+      block.call(doc)
+      doc.save(path)
+      doc
+    end
+
+    def initialize
+      @nodes = []
+      @format_stack = []
+      @current_target = nil
+      @current_list = nil
+      @current_table = nil
+      @current_row = nil
+      @num_id_counter = 0
+      @images = {}
+      @styles = {}
+      register_built_in_styles
+    end
+
+    def define_style(name, **properties)
+      @styles[name] = Style.new(name, **properties)
+    end
+
+    def style(name)
+      @styles[name]
+    end
+
+    def save(path)
+      Package.new(self).save(path)
+    end
+
+    def lists
+      @nodes.select { |n| n.is_a?(Nodes::List) }
+    end
+
+    def images
+      @images.values
+    end
+
+    def register_image(path, width: nil, height: nil)
+      return @images[path] if @images[path]
+
+      rid = next_image_rid
+      width_emu, height_emu = ImageDimensions.calculate_emus(path, width: width, height: height)
+      image = Nodes::Image.new(path, rid: rid, width_emu: width_emu, height_emu: height_emu)
+      @images[path] = image
+      image
+    end
+
+    private
+
+    def next_image_rid
+      # rId1 = styles.xml (always present)
+      # rId2 = numbering.xml (if lists present)
+      # rId3+ = images
+      base = lists.any? ? 3 : 2
+      "rId#{base + @images.size}"
+    end
+
+    def register_built_in_styles
+      # Headings (spacing_before ensures they're rendered as paragraph styles)
+      define_style :heading1, size: 24, bold: true, spacing_before: 240, spacing_after: 120
+      define_style :heading2, size: 18, bold: true, spacing_before: 200, spacing_after: 100
+      define_style :heading3, size: 14, bold: true, spacing_before: 160, spacing_after: 80
+      define_style :heading4, size: 12, bold: true, spacing_before: 120, spacing_after: 60
+      define_style :heading5, size: 11, bold: true, italic: true, spacing_before: 100, spacing_after: 40
+      define_style :heading6, size: 10, bold: true, italic: true, spacing_before: 80, spacing_after: 40
+
+      # Other built-in styles
+      define_style :title, size: 26, bold: true, align: :center
+      define_style :subtitle, size: 15, italic: true, color: "666666"
+      define_style :quote, italic: true, color: "666666", indent: 720
+      define_style :code, font: "Courier New", size: 10
+    end
+  end
+end

data/lib/notare/image_dimensions.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "fastimage"
+
+module Notare
+  class ImageDimensions
+    EMUS_PER_INCH = 914_400
+    DEFAULT_DPI = 96
+
+    def self.read(path)
+      FastImage.size(path) || raise(ArgumentError, "Could not read image dimensions: #{path}")
+    end
+
+    def self.calculate_emus(path, width: nil, height: nil)
+      native_width, native_height = read(path)
+      calculate_dimensions_emu(native_width, native_height, width, height)
+    end
+
+    def self.calculate_dimensions_emu(native_width, native_height, width, height)
+      if width && height
+        [parse_dimension(width), parse_dimension(height)]
+      elsif width
+        w = parse_dimension(width)
+        ratio = native_height.to_f / native_width
+        [w, (w * ratio).to_i]
+      elsif height
+        h = parse_dimension(height)
+        ratio = native_width.to_f / native_height
+        [(h * ratio).to_i, h]
+      else
+        pixels_to_emus(native_width, native_height)
+      end
+    end
+
+    def self.parse_dimension(value)
+      case value
+      when Integer
+        pixels_to_emus(value, 0).first
+      when /\A(\d+(?:\.\d+)?)\s*in\z/i
+        (::Regexp.last_match(1).to_f * EMUS_PER_INCH).to_i
+      when /\A(\d+(?:\.\d+)?)\s*cm\z/i
+        (::Regexp.last_match(1).to_f * 360_000).to_i
+      when /\A(\d+(?:\.\d+)?)\s*px\z/i, /\A(\d+)\z/
+        pixels_to_emus(::Regexp.last_match(1).to_i, 0).first
+      else
+        raise ArgumentError, "Invalid dimension format: #{value}. Use '2in', '5cm', '100px', or integer pixels."
+      end
+    end
+
+    def self.pixels_to_emus(width_px, height_px)
+      emu_per_pixel = EMUS_PER_INCH / DEFAULT_DPI
+      [(width_px * emu_per_pixel).to_i, (height_px * emu_per_pixel).to_i]
+    end
+  end
+end

data/lib/notare/nodes/base.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Notare
+  module Nodes
+    class Base
+      # Base class for all document nodes
+    end
+  end
+end

data/lib/notare/nodes/image.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Notare
+  module Nodes
+    class Image < Base
+      attr_reader :path, :width_emu, :height_emu, :rid, :filename
+
+      EMUS_PER_INCH = 914_400
+      EMUS_PER_CM = 360_000
+      DEFAULT_DPI = 96
+
+      def initialize(path, rid:, width_emu:, height_emu:)
+        super()
+        @path = path
+        @rid = rid
+        @width_emu = width_emu
+        @height_emu = height_emu
+        @filename = "image#{rid.delete_prefix("rId")}.#{extension}"
+      end
+
+      def extension
+        case File.extname(@path).downcase
+        when ".png" then "png"
+        when ".jpg", ".jpeg" then "jpeg"
+        else raise ArgumentError, "Unsupported image format: #{File.extname(@path)}"
+        end
+      end
+
+      def content_type
+        extension == "png" ? "image/png" : "image/jpeg"
+      end
+
+      def doc_pr_id
+        rid.delete_prefix("rId").to_i
+      end
+    end
+  end
+end