[latex3-commits] [latex3/latex3] object-tracking: Add support for indexed PDF objects (c2eba0d79)
github at latex-project.org
github at latex-project.org
Thu Mar 28 15:48:54 CET 2024
Repository : https://github.com/latex3/latex3
On branch : object-tracking
Link : https://github.com/latex3/latex3/commit/c2eba0d7911eb4da32333ea76730099cf7fbc4de
>---------------------------------------------------------------
commit c2eba0d7911eb4da32333ea76730099cf7fbc4de
Author: Joseph Wright <joseph at texdev.net>
Date: Thu Mar 28 14:26:21 2024 +0000
Add support for indexed PDF objects
The name includes 'indexed' as there are a set of
deprecated functions which have one addition "n" compared
to those we now promote - thus we can't use that approach and need a new name,
>---------------------------------------------------------------
c2eba0d7911eb4da32333ea76730099cf7fbc4de
l3kernel/CHANGELOG.md | 3 +
l3kernel/l3pdf.dtx | 168 ++++++++++++++++++++++++++++++++++++++++++++------
2 files changed, 151 insertions(+), 20 deletions(-)
diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index d1bf5e43a..b6b0a885d 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -7,6 +7,9 @@ this project uses date-based 'snapshot' version identifiers.
## [Unreleased]
+### Added
+- Support for 'indexed' PDF objects
+
### Changed
- Expand object names in `\pdf_object_...` functions (issue \#1521)
diff --git a/l3kernel/l3pdf.dtx b/l3kernel/l3pdf.dtx
index 2cd6fd571..00e125c5d 100644
--- a/l3kernel/l3pdf.dtx
+++ b/l3kernel/l3pdf.dtx
@@ -51,6 +51,8 @@
%
% \section{Objects}
%
+% \subsection{Named objects}
+%
% An \meta{object} name should fully expand to tokens suitable for use in a
% label-like context.
%
@@ -89,6 +91,58 @@
% in for example page resource allocation
% \end{function}
%
+% \begin{function}[EXP, pTF, added = 2020-05-15]{\pdf_object_if_exist:n}
+% \begin{syntax}
+% \cs{pdf_object_if_exist_p:n} \Arg{object}
+% \cs{pdf_object_if_exist:nTF} \Arg{object}
+% \end{syntax}
+% Tests whether an object with name \Arg{object} has been defined.
+% \end{function}
+%
+% \subsection{Indexed objects}
+%
+% Objects can be created using a \meta{class} and \emph{index}. For large
+% families of objects, this approach is more efficient than using individual names.
+%
+% \begin{function}[added = 2024-03-28]{\pdf_object_new_indexed:nn}
+% \begin{syntax}
+% \cs{pdf_object_new_indexed:nn} \Arg{class} \Arg{index}
+% \end{syntax}
+% Declares a PDF object of \meta{class} and \meta{index}. The object may be
+% referenced from this point on, and written later using
+% \cs{pdf_object_write_indexed:nnnn}.
+% \end{function}
+%
+% \begin{function}[added = 2024-03-28]
+% {\pdf_object_write_indexed:nnnn, \pdf_object_write_indexed:nnne}
+% \begin{syntax}
+% \cs{pdf_object_write_indexed:nnnn} \Arg{class} \Arg{index} \Arg{type} \Arg{content}
+% \end{syntax}
+% Writes the \meta{content} as content of the onject of \meta{class} and
+% \meta{index}. Depending on the
+% \meta{type} declared for the object, the format required for the
+% \meta{data} will vary
+% \begin{itemize}
+% \item[\texttt{array}] A space-separated list of values
+% \item[\texttt{dict}] Key--value pairs in the form
+% \texttt{/\meta{key} \meta{value}}
+% \item[\texttt{fstream}] Two brace groups: \meta{file name} and
+% \meta{file content}
+% \item[\texttt{stream}] Two brace groups: \meta{attributes (dictionary)}
+% and \meta{stream contents}
+% \end{itemize}
+% \end{function}
+%
+% \begin{function}[EXP, added = 2024-03-28]{\pdf_object_ref_indexed:nn}
+% \begin{syntax}
+% \cs{pdf_object_ref_indexed:nn} \Arg{class} \Arg{index}
+% \end{syntax}
+% Inserts the appropriate information to reference the object of \meta{class}
+% and \meta{index} in for example page resource allocation
+% \end{function}
+%
+% \subsection{General functions}
+%
% \begin{function}[added = 2021-02-10]
% {\pdf_object_unnamed_write:nn, \pdf_object_unnamed_write:ne}
% \begin{syntax}
@@ -122,14 +176,6 @@
% Inserts the appropriate information to reference the \meta{pageobject}.
% \end{function}
%
-% \begin{function}[EXP, pTF, added = 2020-05-15]{\pdf_object_if_exist:n}
-% \begin{syntax}
-% \cs{pdf_object_if_exist_p:n} \Arg{object}
-% \cs{pdf_object_if_exist:nTF} \Arg{object}
-% \end{syntax}
-% Tests whether an object with name \Arg{object} has been defined.
-% \end{function}
-%
% \section{Version}
%
% \begin{function}[pTF, EXP, added = 2021-02-10]{\pdf_version_compare:Nn}
@@ -364,6 +410,100 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}[pTF]{\pdf_object_if_exist:n}
+% Check for an existing assignment.
+% \begin{macrocode}
+\prg_new_conditional:Npnn \pdf_object_if_exist:n #1 { p , T , F , TF }
+ {
+ \int_if_exist:cTF { c_@@_object_ #1 _int }
+ \prg_return_true:
+ \prg_return_false:
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{variable}{\c_@@_object_block_int}
+% Sets the block size used for managing indexed objects.
+% \begin{macrocode}
+\int_const:Nn \c_@@_object_block_int { 10000 }
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{macro}{\pdf_object_new_indexed:nn}
+% \begin{macro}{\@@_object_new_indexed:nnn}
+% \begin{macro}{\pdf_object_write_indexed:nnnn, \pdf_object_write_indexed:nnne}
+% \begin{macro}{\@@_object_write_indexed:nnnnn}
+% \begin{macro}[EXP]{\pdf_object_ref_indexed:nn}
+% \begin{macro}[EXP]{\@@_object_ref_indexed:nnn}
+% \begin{macro}[EXP]{\@@_object_indexed_split:nnN}
+% Using indexed values is much the same, except we have to split up the
+% value. As that's repetitive, we use a single auxiliary.
+% \begin{macrocode}
+\cs_new_protected:Npn \pdf_object_new_indexed:nn #1#2
+ {
+ \@@_object_indexed_split:nnN {#1} {#2}
+ \@@_object_new_indexed:nnn
+ }
+\cs_new_protected:Npn \@@_object_new_indexed:nnn #1#2#3
+ {
+ \@@_backend_object_new:
+ \intarray_if_exist:cF { g_@@_object_ #1 _ #2 _intarray }
+ {
+ \intarray_new:cn { g_@@_object_ #1 _ #2 _intarray }
+ \c_@@_object_block_int
+ }
+ \intarray_gset:cnn { g_@@_object_ #1 _ #2 _intarray }
+ {#3} \g_@@_backend_object_int
+ }
+\cs_new_protected:Npn \pdf_object_write_indexed:nnnn #1#2#3#4
+ {
+ \@@_object_indexed_split:nnN {#1} {#2}
+ \@@_object_new_write:nnnnn
+ {#3} {#4}
+ }
+\cs_generate_variant:Nn \pdf_object_write_indexed:nnnn { nnne }
+\cs_new_protected:Npn \@@_object_write_indexed:nnnnn #1#2#3#4#5
+ {
+ \exp_args:Ne \@@_backend_object_write:nnn
+ { \intarray_item:cn { g_@@_object_ #1 _ #2 _intarray } {#3} }
+ {#4} {#5}
+ \bool_gset_true:N \g_@@_init_bool
+ }
+\cs_new:Npn \pdf_object_ref:nn #1#2
+ {
+ \@@_object_indexed_split:nnN {#1} {#2}
+ \@@_object_ref_indexed:nnn
+ }
+\cs_new:Npn \@@_object_ref_indexed:nnn #1#2#3
+ {
+ \exp_args:Ne \@@_backend_object_ref:n
+ { \intarray_item:cn { g_@@_object_ #1 _ #2 _intarray } {#3} }
+ }
+\cs_new:Npn \@@_object_indexed_split:nnN #1#2#3
+ {
+ \use:e
+ {
+ \exp_not:N #3
+ {#1}
+ {
+ \int_eval:n
+ { \int_div_truncate:nn {#2} \c_@@_object_block_int }
+ }
+ {
+ \int_eval:n
+ { \int_mod:nn {#2} \c_@@_object_block_int }
+ }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}
% {
% \pdf_object_unnamed_write:nn, \pdf_object_unnamed_write:ne,
@@ -387,18 +527,6 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}[pTF]{\pdf_object_if_exist:n}
-% Check for an existing assignment.
-% \begin{macrocode}
-\prg_new_conditional:Npnn \pdf_object_if_exist:n #1 { p , T , F , TF }
- {
- \int_if_exist:cTF { c_@@_object_ #1 _int }
- \prg_return_true:
- \prg_return_false:
- }
-% \end{macrocode}
-% \end{macro}
-%
% \begin{macro}{\pdf_pageobject_ref:n}
% \begin{macrocode}
\cs_new:Npn \pdf_pageobject_ref:n #1
More information about the latex3-commits
mailing list.