carve-hexapdf 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d47fc98c98ecd21adba76ed8abb6150aabe535bcb99ad844b6f48705f115dce8
-  data.tar.gz: 3213a192f274a65f6e262ac73009dda8d33d88945406b20096120ce38d5a6158
+  metadata.gz: 45c5c94de95a03c35c6a7ea92a22aff7fec66c96ff2a5dc44cb36a43034426d8
+  data.tar.gz: 0e3560d71885dd7476d999ab910a2ea0ba9b111c7dccb678979c238e26e9d63c
 SHA512:
-  metadata.gz: 84ad78a47f2cbb33608373ed0d05e3af1f7a14b2f250ed193ad42586bce5e3bae4bdd0b58659517d58e410e6d5f2d7d4a739d9aacd167597c2ff1ffc44a5834d
-  data.tar.gz: 8f88fe4e7cfb412788e3d4c045937db3a03707d891221561ab181485fc6026577cfbbc058c74334c1a5fb4cd07d38dce5d3a4b21bc1f98024142d8e42731ee89
+  metadata.gz: 45f2c67a07e0036a07d862bb7cd42641bfae6a8123b668ab6b910bd67dd54a78d49f4dbe0e83a8f8f25e432207391c0b9377e13d9abf1c2f56eee95b5cf151b8
+  data.tar.gz: b18adba4f2de1b2d2678baa7adb7ac15ce5d8d581b7ca561e186e3c2b33c0bf387b2ba58b6a336669cf33642772cbdd1cbadb06142567a5a827e53f0908f02f6

data/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2] - 2026-09-19
+
+### Fixed
+
+- **A substitution no longer vanishes from the page.** The inline renderer
+  dispatched on `critic_substitute` and read `new_text`; the engine publishes
+  `substitution`, whose halves are the inline arrays `old` and `new`
+  (markup-carve/carve-js#1827). The arm never fired, and the node has no
+  `children`, so the fallback rendered nothing at all. Both halves now reach the
+  page, struck for the replaced run and underlined for the replacement, matching
+  the reference ANSI and HTML renderers.
+  markup-carve/carve-hexapdf#39
+- **Inserted and deleted runs are decorated again.** The same mismatch on two
+  more arms: the dispatch read `critic_insert` and `critic_delete` where the
+  engine publishes `insert` and `delete`. Their text still reached the page
+  through the fallback, so what was lost was the underline and the
+  strikethrough, leaving an editorial mark indistinguishable from body text.
+  markup-carve/carve-hexapdf#41
+
+### Added
+
+- `Carve::Hexapdf.render_from_file(path)` renders the Carve document at `path`
+  with its `{{ path }}` includes expanded, contained to the file's own directory
+  by default and to `include_root:` when one is named. String input stays
+  literal. `on_includes:` hands the caller the warnings and the dependency
+  identities; without it the sanitized warnings go to stderr. `extensions:` and
+  `profile:` are accepted on that path and reach an included child.
+  markup-carve/carve-hexapdf#36
+
+### Changed
+
+- The development engine pin moves to carve-rb `main`, past
+  markup-carve/carve-rb#130, which exposes `Carve.parse_with_includes`, carries
+  the render options into a child, and publishes the substitution halves as
+  inline arrays. The supported consumer range is unchanged: no released
+  `carve-lang` carries the new halves yet, so a consumer resolving through that
+  range still sees a substitution render as nothing until carve-rb publishes.
+
+## [0.1.1] - 2026-08-27
+
+### Changed
+
+- The development pin moves to released `carve-lang` 0.1.2, so the suite covers
+  the current embedded engine and output surface. The supported consumer range
+  remains `>= 0.1.1, < 0.2.0`: 0.1.1 still satisfies this renderer's API and
+  security requirements. On the engine's own 0.x scheme `0.1` is the major and the third digit
+  the minor, so the previous open range admitted, by the engine's own rules, a
+  release declared breaking - and this gem reads an AST whose node vocabulary
+  was already renamed once inside 0.1
+  ([#26](https://github.com/markup-carve/carve-hexapdf/issues/26)).
+
 ## [0.1.0] - 2026-08-19
 
 ### Added
@@ -38,7 +89,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   URLs show alt text, raw HTML and comments are dropped; the renderer never
   raises.
 
-[Unreleased]: https://github.com/markup-carve/carve-hexapdf/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/markup-carve/carve-hexapdf/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/markup-carve/carve-hexapdf/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/markup-carve/carve-hexapdf/releases/tag/v0.1.0
 
 - **Composite figures render as one grouped float.** A bare `::: figure`

data/README.md

@@ -54,6 +54,50 @@ ast = Carve.parse("# From AST")
 pdf_bytes = Carve::Hexapdf.render_ast(ast)
 ```
 
+### Includes
+
+A Carve document can pull another file in with `{{ path }}`. A String has no
+identity of its own, so a directive in one stays literal; name the file instead
+and it expands:
+
+```ruby
+pdf_bytes = Carve::Hexapdf.render_from_file("report/index.crv")
+```
+
+`render_from_file` READS Carve from a path and hands back PDF bytes.
+`render_file` is its opposite pair: it takes Carve source and WRITES the PDF out,
+and a directive in that source stays literal.
+
+Containment defaults to the input file's own directory, so a sibling or a file
+below it resolves and nothing above it does. `include_root:` moves that root:
+
+```ruby
+Carve::Hexapdf.render_from_file("report/index.crv", include_root: "/srv/docs")
+```
+
+The root must be **absolute**. A relative one is refused rather than resolved,
+because resolving it lands on whatever directory the process happens to run in,
+which is not a root anyone chose. The named document has to sit inside the root.
+
+A target that cannot be read leaves the directive drawn as written, and the
+reason goes to stderr. The message does not say whether the file was missing or
+refused by containment: both report `include-unresolved`, so a document cannot
+be used to probe the filesystem. Pass `on_includes:` to take reporting over and
+get the dependency identities with it:
+
+```ruby
+Carve::Hexapdf.render_from_file(
+  "report/index.crv",
+  on_includes: lambda { |warnings:, dependencies:, suppressed_warnings:|
+    dependencies.each { |d| puts "#{d[:path]} #{d[:resolved] ? 'read' : d[:denial]}" }
+  }
+)
+```
+
+`extensions:` and `profile:` reach the engine on the include path, and a child
+file is parsed with the same ones as its parent. Without a root they raise,
+rather than being dropped: `Carve.parse` accepts neither.
+
 ### Options
 
 | Option | Default | Meaning |
@@ -215,6 +259,10 @@ always produces a PDF:
   fetching. Local files and `data:` URIs are embedded.
 - **Raw HTML** blocks/inlines and **comments** are dropped.
 
+## Development
+
+Contributor setup, testing, and maintenance notes are in the [development guide](docs/development.md).
+
 ## Licensing
 
 This gem is **MIT** licensed. However, **HexaPDF is dual-licensed AGPL-3.0 /
@@ -224,7 +272,3 @@ application) or hold a
 [HexaPDF commercial license](https://hexapdf.gettalong.org/#pricing). This gem
 only bridges Carve to HexaPDF; your use of HexaPDF is governed by HexaPDF's own
 terms.
-
-## License
-
-MIT, markup-carve. See [LICENSE](LICENSE).

data/lib/carve/hexapdf/renderer.rb

@@ -566,9 +566,14 @@ module Carve
         when "abbreviation"   then out << run(node[:abbr].to_s, ctx)
         when "cross_ref"      then out << run(node[:target].to_s, ctx)
         when "caption_number" then (out << run(node[:number].to_s, ctx) if node[:number])
-        when "critic_insert"  then emit_children(node, ctx.merge(underline: true), out)
-        when "critic_delete"  then emit_children(node, ctx.merge(strike: true), out)
-        when "critic_substitute" then out << run(node[:new_text].to_s, ctx.merge(underline: true))
+        when "insert" then emit_children(node, ctx.merge(underline: true), out)
+        when "delete" then emit_children(node, ctx.merge(strike: true), out)
+        # Both halves are inline arrays, and both reach the page: struck for the
+        # replaced run, underlined for the replacement, which is what the
+        # reference ANSI and HTML renderers show.
+        when "substitution"
+          emit_children({ children: node[:old] }, ctx.merge(strike: true), out)
+          emit_children({ children: node[:new] }, ctx.merge(underline: true), out)
         when "smart_punctuation" then out << run(smart_punctuation_text(node), ctx)
         # A character the author escaped. The backslash is authoring syntax, so
         # the page shows the character - but the node has no children, so
@@ -877,8 +882,8 @@ module Carve
       INLINE_TYPES = %w[
         text emphasis code link image span math raw_inline emoji autolink
         cross_ref caption_number mention tag citation_group inline_extension
-        abbreviation footnote soft_break hard_break critic_insert critic_delete
-        critic_substitute critic_comment
+        abbreviation footnote soft_break hard_break insert delete
+        substitution critic_comment
       ].freeze
     end
   end

data/lib/carve/hexapdf/version.rb

@@ -2,6 +2,6 @@
 
 module Carve
   module Hexapdf
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/carve/hexapdf.rb

@@ -45,8 +45,31 @@ module Carve
       #                 +:bytes+ and optional +:width+/+:height+ (points) to
       #                 control the drawn size; anything else degrades the
       #                 construct to its monospace source.
-      def render(source, **opts)
-        render_ast(::Carve.parse(source), **opts)
+      def render(source, include_root: nil, source_path: nil, extensions: nil,
+                 profile: nil, on_includes: nil, **opts)
+        ast = parse_source(source, include_root: include_root, source_path: source_path,
+                           extensions: extensions, profile: profile,
+                           on_includes: on_includes)
+        render_ast(ast, **opts)
+      end
+
+      # Render the Carve document at +path+, with its <tt>{{ path }}</tt>
+      # includes expanded, and return the PDF bytes.
+      #
+      #   Carve::Hexapdf.render_from_file("report/index.crv")
+      #
+      # NOT to be confused with {render_file}, which takes Carve SOURCE and
+      # writes the PDF out. This one READS the Carve and hands the bytes back.
+      #
+      # Containment defaults to the input file's own directory, so a sibling or
+      # a file below it resolves and nothing above it does. +include_root:+
+      # widens or moves that root, and reaches the engine as the caller wrote
+      # it: the engine refuses a relative root, which is what keeps containment
+      # off whatever directory the process happens to run in.
+      def render_from_file(path, include_root: nil, **opts)
+        absolute = File.expand_path(path)
+        root = include_root || File.dirname(absolute)
+        render(File.read(absolute), include_root: root, source_path: absolute, **opts)
       end
 
       # Render an already-parsed Carve AST Hash (see +Carve.parse+) to PDF
@@ -62,10 +85,64 @@ module Carve
       end
 
       # Render Carve +source+ and write the PDF to +path+. Returns +path+.
+      #
+      # +source+ is a String with no identity of its own, so a directive stays
+      # literal unless the caller names both +include_root:+ and +source_path:+.
       def render_file(source, path, **opts)
         File.binwrite(path, render(source, **opts))
         path
       end
+
+      private
+
+      # The AST to draw: expanded when the caller named a root and a document.
+      #
+      # A String reaching this with neither is parsed as it stands, so a
+      # directive in it is text. That is the only thing a caller with no file
+      # can be given: a relative include has nothing to resolve against.
+      def parse_source(source, include_root:, source_path:, extensions:, profile:,
+                       on_includes:)
+        if include_root.nil? || source_path.nil?
+          unless extensions.nil? && profile.nil?
+            raise ArgumentError,
+                  "extensions: and profile: reach the engine on the include path only; " \
+                  "pass include_root: and source_path:, or drop them"
+          end
+
+          return ::Carve.parse(source)
+        end
+
+        result = ::Carve.parse_with_includes(source, root: include_root,
+                                                     source_path: source_path,
+                                                     extensions: extensions,
+                                                     profile: profile)
+        report_includes(result, on_includes)
+        result[:value]
+      end
+
+      # Hand the caller everything expansion found, or say what degraded.
+      #
+      # With +on_includes:+ the caller owns reporting and gets the dependency
+      # identities with it. Without it the sanitized warnings go to stderr,
+      # because a document that silently lost half its content is the failure
+      # this exists to prevent.
+      def report_includes(result, on_includes)
+        if on_includes
+          on_includes.call(warnings: Array(result[:warnings]),
+                           dependencies: Array(result[:dependencies]),
+                           suppressed_warnings: result[:suppressedWarnings].to_i)
+          return
+        end
+
+        Array(result[:warnings]).each do |warning|
+          where = warning[:file] ? "#{warning[:file]}: " : ""
+          $stderr.puts "carve-hexapdf: #{where}#{warning[:rule]}: #{warning[:message]}"
+        end
+        suppressed = result[:suppressedWarnings].to_i
+        return unless suppressed.positive?
+
+        $stderr.puts "carve-hexapdf: #{suppressed} further include warnings suppressed"
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: carve-hexapdf
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: carve-lang
@@ -17,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,6 +27,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.1.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: hexapdf
   requirement: !ruby/object:Gem::Requirement
@@ -107,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Render the Carve markup language to PDF via the pure-Ruby HexaPDF engine.