pd4ml 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e64864df0fb4496d031d723120f675781e9212886577f4dc499acc80f31c4516
-  data.tar.gz: 29610ecaa6be3bd219b85d457049060edfca8432c10b5c398ff255a375abc675
+  metadata.gz: eada212500d1ee924117e4c9b8f0ad4f8d29f7b69fb4ff6b0b1775caf3c23bfe
+  data.tar.gz: c3f70c2b02f24e52517d95b4bb10ee2c81116230b9b8d356ccae0f7619b4bf74
 SHA512:
-  metadata.gz: 7e4ba762f395543307059f5c4b1842e6bc33f167f2a8b03d5d41127a6e95c63bb7963375c1880963c370ba8b98a882d951cca1da1a3bcbdfaf0465e754968906
-  data.tar.gz: 1f235d8f8b872d6bba0ed332ac8d765a84fd3c17c73b9102260b3d037258c1007f2c6c7d17896cf2eb20a6d675a86dc61eca928da824aae811b1933d6496a671
+  metadata.gz: f6f7e9b5e9ff21c9db8a8cbae74770c766444afd2c9ce6123a08817691c9dfac6c941104a12cf56f2614d4274e858df788baaeb986a8ecd88d5c246128f0a8c1
+  data.tar.gz: ad146b82b276a72480749a4f2f25e3254b982e8d1a3dfd4d065e202e06b61496c6b4e250abddf5aac44a5f29150259cdb0f57853ea132b3be0d75dc5740bafc9

data/README.md

@@ -16,29 +16,30 @@ pd.write_pdf('hello.pdf')          # or pdf = pd.write_pdf (a binary String), or
 
 ## Installation
 
-With Bundler, in the `Gemfile`:
-
-```ruby
-gem 'pd4ml', git: 'https://github.com/zxfr/pd4ml-ruby.git'
-```
-
-or download the gem from <https://github.com/zxfr/pd4ml-ruby/releases>:
-
 ```
-gem install pd4ml-1.0.0.gem
+gem install pd4ml
 pd4ml install            # optional: otherwise the first use downloads PD4ML
 ```
 
+or `gem 'pd4ml'` in the `Gemfile`. The gem is on RubyGems (<https://rubygems.org/gems/pd4ml>);
+its contents and releases are also on GitHub (<https://github.com/zxfr/pd4ml-ruby>).
+
 Requirements:
 
 - Ruby 3.1 or later.
 - Java 8 or later, found through `PD4ML_JAVA`, `JAVA_HOME` or the `PATH`.
 
-PD4ML itself is downloaded from <https://pd4ml.com/maven2>: the most recent 4.x release, plus the
-Bouncy Castle jars it needs for encryption and signing. Every file is checked against its SHA-1
-checksum. The download happens with `pd4ml install`, or on first use (`PD4ML_AUTO_INSTALL=0`
-turns that off). Builds are stored per user (`%LOCALAPPDATA%\pd4ml-ruby`, `~/.cache/pd4ml-ruby`,
-or `PD4ML_HOME`).
+PD4ML itself is downloaded from <https://pd4ml.com/maven2>: by default the most recent release from
+4.2.0 on, plus the Bouncy Castle jars it needs for encryption and signing. Every file is checked
+against its SHA-1 checksum. The download happens with `pd4ml install`, or on first use
+(`PD4ML_AUTO_INSTALL=0` turns that off). Builds are stored per user
+(`%LOCALAPPDATA%\pd4ml-ruby`, `~/.cache/pd4ml-ruby`, or `PD4ML_HOME`).
+
+The gem's PD4ML 4.2 API (`read_eml`/`read_mht`, `add_allowed_resource_location`, XMP
+`add_metadata`, the DOM API) needs PD4ML 4.2. Until PD4ML 4.2.0 is released, the default is
+therefore the most recent 4.2.x development snapshot (4.2.0-SNAPSHOT). Once 4.2.0 is out, new
+installs take it, and `pd4ml install` updates existing ones. `pd4ml install 4.1.2` installs the
+current 4.1 release instead (the rest of the API works with it). See [Install PD4ML](docs/guide.md#22-install-pd4ml).
 
 To use a PD4ML jar of your own, set `PD4ML_CLASSPATH`, set `PD4ML_CLASSPATH_FILE`, or call
 `Pd4ml.configure(classpath: [...])`.
@@ -56,10 +57,15 @@ The gem adds Ruby I/O on top: paths, URLs, binary Strings and IO objects in and
 for progress listeners. Several processes can share one bridge server: run `pd4ml serve` and set
 `PD4ML_BRIDGE=tcp://127.0.0.1:8723`.
 
+With PD4ML 4.2, the gem also reads e-mail messages and saved web pages (`read_eml`, `read_mht`),
+and gives access to the parsed document before it is written (`get_document`, `layout`: the DOM
+API of the DMS and UA editions, whose lists come back as Ruby Arrays). See the
+[guide](docs/guide.md#516-e-mail-messages-and-saved-web-pages).
+
 ## Command line
 
 ```
-pd4ml install [VERSION] [--snapshots]   download PD4ML (or update it)
+pd4ml install [VERSION] [--snapshots]   download PD4ML (default: 4.2, see above) or update it
 pd4ml list                              versions in the repository
 pd4ml version                           the PD4ML version in use
 pd4ml convert in.html out.pdf [--page-size A4 --landscape --spec pdf/a-2b ...]

data/docs/api.md

@@ -2,7 +2,7 @@
 
 _Generated by `tools/gen_api.rb` from the PD4ML Java classes - do not edit._
 
-Every public PD4ML class is a Ruby class in the `Pd4ml` module. Methods can be called by their Java name (`setPageSize`) or Ruby-style (`set_page_size`; `isDemoMode` as `demo_mode?`); both are listed below. Constants and static fields are Ruby constants or class methods (`Pd4ml::PageSize::A4`, `Pd4ml::LayoutEngine.v42`), public instance fields are read with `obj[:name]`. Java types appear as Ruby types: binary Strings for `byte[]` and `InputStream`, a path or URL String for `URL`/`File`, `JavaObject` for any other Java object. Descriptions of each method are in the [PD4ML manual](https://pd4ml.com/docs/pd4ml-manual.html).
+Every public PD4ML class is a Ruby class in the `Pd4ml` module. Methods can be called by their Java name (`setPageSize`) or Ruby-style (`set_page_size`; `isDemoMode` as `demo_mode?`); both are listed below. Constants and static fields are Ruby constants or class methods (`Pd4ml::PageSize::A4`, `Pd4ml::LayoutEngine.v42`), public instance fields are read with `obj[:name]`. Java types appear as Ruby types: binary Strings for `byte[]` and `InputStream`, a path or URL String for `URL`/`File`, `JavaObject` for any other Java object. The DOM API classes (`Pd4ml::Dom`: `PD4ML#get_document` and `PD4ML#layout` return them; v42 layout engine, DMS and UA editions) return Java lists and sets as Ruby Arrays, maps as Hashes. Descriptions of each method are in the [PD4ML manual](https://pd4ml.com/docs/pd4ml-manual.html).
 
 ## Pd4ml::PD4ML
 
@@ -78,6 +78,8 @@ keep_trailing_blank_pages?() -> true/false   # isKeepTrailingBlankPages
 test_termination() -> nil   # testTermination
 get_height(width: Integer) -> Integer   # getHeight
 get_document_title() -> String   # getDocumentTitle
+layout() -> Dom::Layout   # layout
+get_document() -> Dom::Document   # getDocument
 set_rendering_hints(hints: Hash) -> nil   # setRenderingHints
 dump(mode: Integer) -> String   # dump
 protect_physical_unit_dimensions(keep_physical_unit_dimensions: true/false) -> nil   # protectPhysicalUnitDimensions
@@ -85,10 +87,12 @@ Pd4ml::PD4ML.translate_to_pt(mm: Float) -> Float   # translateToPt
 Pd4ml::PD4ML.predict_scale(page_margins: PageMargins, page_size: PageSize, user_space: Integer) -> Float   # predictScale
 Pd4ml::PD4ML.predict_page_height(page_margins: PageMargins, page_size: PageSize, user_space: Integer) -> Integer   # predictPageHeight
 set_dynamic_data(map: Hash) -> nil   # setDynamicData
+add_allowed_resource_location(locations: String) -> nil   # addAllowedResourceLocation
 set_param(key: String, value: String) -> nil   # setParam
 get_last_render_info(key: String) -> Object   # getLastRenderInfo
 output_range(description: String) -> nil   # outputRange
 add_metadata(key: String, value: String, hide: true/false) -> nil   # addMetadata
+add_metadata(namespace_uri: String, prefix: String, key: String, value: String) -> nil   # addMetadata
 apply_kerning(enable: true/false) -> nil   # applyKerning
 enable_ligatures(enable: true/false) -> nil   # enableLigatures
 get_cache() -> Object   # getCache
@@ -119,7 +123,6 @@ async_resource_loader(thread_pool_size: Integer) -> nil   # asyncResourceLoader
 | `Pd4ml::Constants::PD4ML_EXTRA_RESOURCE_LOADERS` | String | static read-only |
 | `Pd4ml::Constants::PD4ML_DOCUMENT_VIEW_MODE` | String | static read-only |
 | `Pd4ml::Constants::PD4ML_DOCUMENT_DATE` | String | static read-only |
-| `Pd4ml::Constants::PD4ML_WORD_EDITABLE` | String | static read-only |
 | `Pd4ml::Constants::PD4ML_DOCUMENT_XMP_DATE` | String | static read-only |
 | `Pd4ml::Constants::PD4ML_FAKE_BROWSER` | String | static read-only |
 | `Pd4ml::Constants::PD4ML_CACHE_ENABLE` | String | static read-only |
@@ -398,6 +401,7 @@ requires_metadata() -> true/false   # requiresMetadata
 requires_output_internet() -> true/false   # requiresOutputInternet
 allows_external_hyperlinking() -> true/false   # allowsExternalHyperlinking
 requires_reliable_unicode_semantics() -> true/false   # requiresReliableUnicodeSemantics
+has_pdf_version() -> true/false   # hasPdfVersion
 get_pdf_version_label() -> String   # getPdfVersionLabel
 get_pdf_ext_level() -> Integer   # getPdfExtLevel
 get_pdfa_version() -> Integer   # getPdfaVersion
@@ -450,7 +454,7 @@ Pd4ml::PdfDocumentBase.compute_scope(scope: String, page_num: Integer) -> Array<
 
 ## Pd4ml::PdfDocument
 
-`com.pd4ml.PdfDocument`
+`com.pd4ml.PdfDocument` — also the methods of `Pd4ml::PdfDocumentBase`
 
 ```ruby
 Pd4ml::PdfDocument.new(bytes: String (binary), password: String)
@@ -544,3 +548,151 @@ error?() -> true/false   # isError
 warning?() -> true/false   # isWarning
 get_message() -> String   # getMessage
 ```
+
+## Pd4ml::Dom::Node
+
+`com.pd4ml.dom.Node` (DOM API)
+
+```ruby
+get_node_name() -> String   # getNodeName
+get_parent_node() -> Dom::Node   # getParentNode
+get_parent_element() -> Dom::Element   # getParentElement
+get_owner_document() -> Dom::Document   # getOwnerDocument
+get_child_nodes() -> Array<Dom::Node>   # getChildNodes
+has_child_nodes() -> true/false   # hasChildNodes
+get_first_child() -> Dom::Node   # getFirstChild
+get_last_child() -> Dom::Node   # getLastChild
+get_next_sibling() -> Dom::Node   # getNextSibling
+get_previous_sibling() -> Dom::Node   # getPreviousSibling
+get_text_content() -> String   # getTextContent
+set_text_content(text: String) -> nil   # setTextContent
+append_child(child: Dom::Node) -> Dom::Node   # appendChild
+insert_before(child: Dom::Node, ref: Dom::Node) -> Dom::Node   # insertBefore
+replace_child(replacement: Dom::Node, old: Dom::Node) -> Dom::Node   # replaceChild
+remove_child(child: Dom::Node) -> Dom::Node   # removeChild
+remove() -> nil   # remove
+clone_node(deep: true/false) -> Dom::Node   # cloneNode
+contains(other: Dom::Node) -> true/false   # contains
+to_html() -> String   # toHtml
+```
+
+## Pd4ml::Dom::Document
+
+`com.pd4ml.dom.Document` (DOM API) — also the methods of `Pd4ml::Dom::Node`
+
+```ruby
+get_document_element() -> Dom::Element   # getDocumentElement
+get_head() -> Dom::Element   # getHead
+get_body() -> Dom::Element   # getBody
+get_doctype() -> Dom::DocumentType   # getDoctype
+quirks_mode?() -> true/false   # isQuirksMode
+get_base_uri() -> String   # getBaseURI
+get_title() -> String   # getTitle
+get_element_by_id(id: String) -> Dom::Element   # getElementById
+get_elements_by_tag_name(name: String) -> Array<Dom::Element>   # getElementsByTagName
+get_elements_by_class_name(names: String) -> Array<Dom::Element>   # getElementsByClassName
+query_selector(selectors: String) -> Dom::Element   # querySelector
+query_selector_all(selectors: String) -> Array<Dom::Element>   # querySelectorAll
+create_element(tag_name: String) -> Dom::Element   # createElement
+create_text_node(data: String) -> Dom::Text   # createTextNode
+create_comment(data: String) -> Dom::Comment   # createComment
+set_text_content(text: String) -> nil   # setTextContent
+```
+
+## Pd4ml::Dom::Element
+
+`com.pd4ml.dom.Element` (DOM API) — also the methods of `Pd4ml::Dom::Node`
+
+```ruby
+get_tag_name() -> String   # getTagName
+get_attribute(name: String) -> String   # getAttribute
+has_attribute(name: String) -> true/false   # hasAttribute
+set_attribute(name: String, value: String) -> nil   # setAttribute
+remove_attribute(name: String) -> nil   # removeAttribute
+get_attributes() -> Hash   # getAttributes
+get_id() -> String   # getId
+set_id(id: String) -> nil   # setId
+get_class_name() -> String   # getClassName
+set_class_name(class_name: String) -> nil   # setClassName
+get_class_list() -> Array<String>   # getClassList
+has_class(name: String) -> true/false   # hasClass
+add_class(name: String) -> nil   # addClass
+remove_class(name: String) -> nil   # removeClass
+toggle_class(name: String) -> true/false   # toggleClass
+get_children() -> Array<Dom::Element>   # getChildren
+get_first_element_child() -> Dom::Element   # getFirstElementChild
+get_last_element_child() -> Dom::Element   # getLastElementChild
+get_next_element_sibling() -> Dom::Element   # getNextElementSibling
+get_previous_element_sibling() -> Dom::Element   # getPreviousElementSibling
+get_elements_by_tag_name(name: String) -> Array<Dom::Element>   # getElementsByTagName
+get_elements_by_class_name(names: String) -> Array<Dom::Element>   # getElementsByClassName
+query_selector(selectors: String) -> Dom::Element   # querySelector
+query_selector_all(selectors: String) -> Array<Dom::Element>   # querySelectorAll
+matches(selectors: String) -> true/false   # matches
+closest(selectors: String) -> Dom::Element   # closest
+get_inner_html() -> String   # getInnerHTML
+set_inner_html(html: String) -> nil   # setInnerHTML
+get_outer_html() -> String   # getOuterHTML
+set_outer_html(html: String) -> nil   # setOuterHTML
+set_text_content(text: String) -> nil   # setTextContent
+```
+
+## Pd4ml::Dom::Text
+
+`com.pd4ml.dom.Text` (DOM API) — also the methods of `Pd4ml::Dom::Node`
+
+```ruby
+get_data() -> String   # getData
+set_data(data: String) -> nil   # setData
+whitespace?() -> true/false   # isWhitespace
+set_text_content(text: String) -> nil   # setTextContent
+```
+
+## Pd4ml::Dom::Comment
+
+`com.pd4ml.dom.Comment` (DOM API) — also the methods of `Pd4ml::Dom::Node`
+
+```ruby
+get_data() -> String   # getData
+set_data(data: String) -> nil   # setData
+get_text_content() -> String   # getTextContent
+set_text_content(text: String) -> nil   # setTextContent
+```
+
+## Pd4ml::Dom::DocumentType
+
+`com.pd4ml.dom.DocumentType` (DOM API) — also the methods of `Pd4ml::Dom::Node`
+
+```ruby
+get_name() -> String   # getName
+get_public_id() -> String   # getPublicId
+get_system_id() -> String   # getSystemId
+set_text_content(text: String) -> nil   # setTextContent
+```
+
+## Pd4ml::Dom::Layout
+
+`com.pd4ml.dom.Layout` (DOM API)
+
+```ruby
+get_page_count() -> Integer   # getPageCount
+get_page_width(page: Integer) -> Float   # getPageWidth
+get_page_height(page: Integer) -> Float   # getPageHeight
+get_page_number(page: Integer) -> Integer   # getPageNumber
+get_boxes(element: Dom::Element) -> Array<Dom::LayoutBox>   # getBoxes
+get_pages(element: Dom::Element) -> Array<Integer>   # getPages
+get_computed_style(element: Dom::Element, property: String) -> String   # getComputedStyle
+element_at(page: Integer, x: Float, y: Float) -> Dom::Element   # elementAt
+```
+
+## Pd4ml::Dom::LayoutBox
+
+`com.pd4ml.dom.LayoutBox` (DOM API)
+
+```ruby
+get_page() -> Integer   # getPage
+get_x() -> Float   # getX
+get_y() -> Float   # getY
+get_width() -> Float   # getWidth
+get_height() -> Float   # getHeight
+```