[latex3-commits] [git/LaTeX3-latex3-latex3] main: Switch to keyval approach to graphics data (c210da47f)
Joseph Wright
joseph.wright at morningstar2.co.uk
Wed Apr 6 09:41:55 CEST 2022
Repository : https://github.com/latex3/latex3
On branch : main
Link : https://github.com/latex3/latex3/commit/c210da47f2de142f333afd7ae3f20166af4a9551
>---------------------------------------------------------------
commit c210da47f2de142f333afd7ae3f20166af4a9551
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Wed Apr 6 08:39:43 2022 +0100
Switch to keyval approach to graphics data
>---------------------------------------------------------------
c210da47f2de142f333afd7ae3f20166af4a9551
l3backend/l3backend-graphics.dtx | 108 +++++++--------
l3experimental/l3graphics/l3graphics.dtx | 153 ++++++++++++---------
.../l3graphics/testfiles/m3graphics000.tlg | 2 +-
3 files changed, 140 insertions(+), 123 deletions(-)
diff --git a/l3backend/l3backend-graphics.dtx b/l3backend/l3backend-graphics.dtx
index 82542167c..19dfb14b1 100644
--- a/l3backend/l3backend-graphics.dtx
+++ b/l3backend/l3backend-graphics.dtx
@@ -130,13 +130,13 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_backend_getbb_jpg:n #1
{
- \int_zero:N \l_graphics_page_int
- \tl_clear:N \l_graphics_pagebox_tl
+ \int_zero:N \l_@@_page_int
+ \tl_clear:N \l_@@_pagebox_str
\tl_set:Nx \l_@@_graphics_attr_tl
{
- \tl_if_empty:NF \l_graphics_decodearray_tl
- { :D \l_graphics_decodearray_tl }
- \bool_if:NT \l_graphics_interpolate_bool
+ \tl_if_empty:NF \l_@@_decodearray_str
+ { :D \l_@@_decodearray_str }
+ \bool_if:NT \l_@@_interpolate_bool
{ :I }
}
\tl_clear:N \l_@@_graphics_attr_tl
@@ -145,13 +145,13 @@
\cs_new_eq:NN \@@_backend_getbb_png:n \@@_backend_getbb_jpg:n
\cs_new_protected:Npn \@@_backend_getbb_pdf:n #1
{
- \tl_clear:N \l_graphics_decodearray_tl
- \bool_set_false:N \l_graphics_interpolate_bool
+ \tl_clear:N \l_@@_decodearray_str
+ \bool_set_false:N \l_@@_interpolate_bool
\tl_set:Nx \l_@@_graphics_attr_tl
{
- : \l_graphics_pagebox_tl
- \int_compare:nNnT \l_graphics_page_int > 1
- { :P \int_use:N \l_graphics_page_int }
+ : \l_@@_pagebox_str
+ \int_compare:nNnT \l_@@_page_int > 1
+ { :P \int_use:N \l_@@_page_int }
}
\@@_backend_getbb_auxi:n {#1}
}
@@ -170,21 +170,21 @@
{
\tex_immediate:D \tex_pdfximage:D
\bool_lazy_or:nnT
- { \l_graphics_interpolate_bool }
- { ! \tl_if_empty_p:N \l_graphics_decodearray_tl }
+ { \l_@@_interpolate_bool }
+ { ! \tl_if_empty_p:N \l_@@_decodearray_str }
{
attr ~
{
- \tl_if_empty:NF \l_graphics_decodearray_tl
- { /Decode~[ \l_graphics_decodearray_tl ] }
- \bool_if:NT \l_graphics_interpolate_bool
+ \tl_if_empty:NF \l_@@_decodearray_str
+ { /Decode~[ \l_@@_decodearray_str ] }
+ \bool_if:NT \l_@@_interpolate_bool
{ /Interpolate~true }
}
}
- \int_compare:nNnT \l_graphics_page_int > 0
- { page ~ \int_use:N \l_graphics_page_int }
- \tl_if_empty:NF \l_graphics_pagebox_tl
- { \l_graphics_pagebox_tl }
+ \int_compare:nNnT \l_@@_page_int > 0
+ { page ~ \int_use:N \l_@@_page_int }
+ \tl_if_empty:NF \l_@@_pagebox_str
+ { \l_@@_pagebox_str }
{#1}
\hbox_set:Nn \l_@@_internal_box
{ \tex_pdfrefximage:D \tex_pdflastximage:D }
@@ -295,15 +295,15 @@
%<*dvipdfmx>
\cs_new_protected:Npn \@@_backend_getbb_jpg:n #1
{
- \int_zero:N \l_graphics_page_int
- \tl_clear:N \l_graphics_pagebox_tl
+ \int_zero:N \l_@@_page_int
+ \tl_clear:N \l_@@_pagebox_str
\@@_extract_bb:n {#1}
}
\cs_new_eq:NN \@@_backend_getbb_png:n \@@_backend_getbb_jpg:n
\cs_new_protected:Npn \@@_backend_getbb_pdf:n #1
{
- \tl_clear:N \l_graphics_decodearray_tl
- \bool_set_false:N \l_graphics_interpolate_bool
+ \tl_clear:N \l_@@_decodearray_str
+ \bool_set_false:N \l_@@_interpolate_bool
\@@_extract_bb:n {#1}
}
%</dvipdfmx>
@@ -358,13 +358,13 @@
{
\@@_backend_include_auxii:xnn
{
- \tl_if_empty:NF \l_graphics_pagebox_tl
- { : \l_graphics_pagebox_tl }
- \int_compare:nNnT \l_graphics_page_int > 1
- { :P \int_use:N \l_graphics_page_int }
- \tl_if_empty:NF \l_graphics_decodearray_tl
- { :D \l_graphics_decodearray_tl }
- \bool_if:NT \l_graphics_interpolate_bool
+ \tl_if_empty:NF \l_@@_pagebox_str
+ { : \l_@@_pagebox_str }
+ \int_compare:nNnT \l_@@_page_int > 1
+ { :P \int_use:N \l_@@_page_int }
+ \tl_if_empty:NF \l_@@_decodearray_str
+ { :D \l_@@_decodearray_str }
+ \bool_if:NT \l_@@_interpolate_bool
{ :I }
}
{#1} {#2}
@@ -393,11 +393,11 @@
{
pdf:#3~
@graphic \int_use:c { c_@@_graphics_ #1#2 _int } ~
- \int_compare:nNnT \l_graphics_page_int > 1
- { page ~ \int_use:N \l_graphics_page_int \c_space_tl }
- \tl_if_empty:NF \l_graphics_pagebox_tl
+ \int_compare:nNnT \l_@@_page_int > 1
+ { page ~ \int_use:N \l_@@_page_int \c_space_tl }
+ \tl_if_empty:NF \l_@@_pagebox_str
{
- pagebox ~ \l_graphics_pagebox_tl \c_space_tl
+ pagebox ~ \l_@@_pagebox_str \c_space_tl
bbox ~
\dim_to_decimal_in_bp:n \l_@@_llx_dim \c_space_tl
\dim_to_decimal_in_bp:n \l_@@_lly_dim \c_space_tl
@@ -406,13 +406,13 @@
}
(#1)
\bool_lazy_or:nnT
- { \l_graphics_interpolate_bool }
- { ! \tl_if_empty_p:N \l_graphics_decodearray_tl }
+ { \l_@@_interpolate_bool }
+ { ! \tl_if_empty_p:N \l_@@_decodearray_str }
{
<<
- \tl_if_empty:NF \l_graphics_decodearray_tl
- { /Decode~[ \l_graphics_decodearray_tl ] }
- \bool_if:NT \l_graphics_interpolate_bool
+ \tl_if_empty:NF \l_@@_decodearray_str
+ { /Decode~[ \l_@@_decodearray_str ] }
+ \bool_if:NT \l_@@_interpolate_bool
{ /Interpolate~true> }
>>
}
@@ -456,21 +456,21 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_backend_getbb_jpg:n #1
{
- \int_zero:N \l_graphics_page_int
- \tl_clear:N \l_graphics_pagebox_tl
+ \int_zero:N \l_@@_page_int
+ \tl_clear:N \l_@@_pagebox_str
\@@_backend_getbb_auxi:nN {#1} \tex_XeTeXpicfile:D
}
\cs_new_eq:NN \@@_backend_getbb_png:n \@@_backend_getbb_jpg:n
\cs_new_protected:Npn \@@_backend_getbb_pdf:n #1
{
- \tl_clear:N \l_graphics_decodearray_tl
- \bool_set_false:N \l_graphics_interpolate_bool
+ \tl_clear:N \l_@@_decodearray_str
+ \bool_set_false:N \l_@@_interpolate_bool
\@@_backend_getbb_auxi:nN {#1} \tex_XeTeXpdffile:D
}
\cs_new_protected:Npn \@@_backend_getbb_auxi:nN #1#2
{
- \int_compare:nNnTF \l_graphics_page_int > 1
- { \@@_backend_getbb_auxii:VnN \l_graphics_page_int {#1} #2 }
+ \int_compare:nNnTF \l_@@_page_int > 1
+ { \@@_backend_getbb_auxii:VnN \l_@@_page_int {#1} #2 }
{ \@@_backend_getbb_auxiii:nNnn {#1} #2 { :P 1 } { page 1 } }
}
\cs_new_protected:Npn \@@_backend_getbb_auxii:nnN #1#2#3
@@ -478,8 +478,8 @@
\cs_generate_variant:Nn \@@_backend_getbb_auxii:nnN { V }
\cs_new_protected:Npn \@@_backend_getbb_auxiii:nNnn #1#2#3#4
{
- \tl_if_empty:NTF \l_graphics_pagebox_tl
- { \@@_backend_getbb_auxiv:VnNnn \l_graphics_pagebox_tl }
+ \tl_if_empty:NTF \l_@@_pagebox_str
+ { \@@_backend_getbb_auxiv:VnNnn \l_@@_pagebox_str }
{ \@@_backend_getbb_auxv:nNnn }
{#1} #2 {#3} {#4}
}
@@ -525,9 +525,9 @@
{
\tex_XeTeXpdffile:D
\@@_backend_include_pdf_quote:w #1 "#1" \s_@@_stop \c_space_tl
- \int_compare:nNnT \l_graphics_page_int > 0
- { page ~ \int_use:N \l_graphics_page_int \c_space_tl }
- \exp_after:wN \@@_backend_getbb_pagebox:w \l_graphics_pagebox_tl
+ \int_compare:nNnT \l_@@_page_int > 0
+ { page ~ \int_use:N \l_@@_page_int \c_space_tl }
+ \exp_after:wN \@@_backend_getbb_pagebox:w \l_@@_pagebox_str
}
\cs_new:Npn \@@_backend_include_pdf_quote:w #1 " #2 " #3 \s_@@_stop
{ " #2 " }
@@ -557,8 +557,8 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_backend_getbb_jpg:n #1
{
- \int_zero:N \l_graphics_page_int
- \tl_clear:N \l_graphics_pagebox_tl
+ \int_zero:N \l_@@_page_int
+ \tl_clear:N \l_@@_pagebox_str
\@@_extract_bb:n {#1}
}
\cs_new_eq:NN \@@_backend_getbb_png:n \@@_backend_getbb_jpg:n
@@ -570,8 +570,8 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_backend_getbb_pdf:n #1
{
- \tl_clear:N \l_graphics_decodearray_tl
- \bool_set_false:N \l_graphics_interpolate_bool
+ \tl_clear:N \l_@@_decodearray_str
+ \bool_set_false:N \l_@@_interpolate_bool
\@@_extract_bb:n {#1}
}
% \end{macrocode}
diff --git a/l3experimental/l3graphics/l3graphics.dtx b/l3experimental/l3graphics/l3graphics.dtx
index d0a926068..893685a47 100644
--- a/l3experimental/l3graphics/l3graphics.dtx
+++ b/l3experimental/l3graphics/l3graphics.dtx
@@ -54,49 +54,59 @@
%
% \section{\pkg{l3graphics} documentation}
%
-% \subsection{Graphics data}
+% \subsection{Graphics keys}
%
% Inclusion of graphic files requires a range of low-level data be passed to
-% the backend. This is set up using a small number of variables.
+% the backend. This is set up using a small number of key--value settings,
+% which are stored in the |graphics| tree.
%
-% \begin{variable}{\l_graphics_decodearray_tl}
+% \begin{variable}{decodearray}
% Array to decode color in bitmap graphic: when non-empty, this should
% be in the form of one, two or three pairs of real numbers in the range
% $[0,1]$, separated by spaces.
% \end{variable}
%
-% \begin{variable}{\l_graphics_interpolate_bool}
-% Indicates whether interpolation should be applied to bitmap graphic files.
+% \begin{variable}{draft}
+% Switch to enable draft mode: graphics are read but not included when this is
+% true.
+% \end{variable}
+%
+% \begin{variable}{interpolate}
+% Switch which indicates whether interpolation should be applied to bitmap
+% graphic files.
% \end{variable}
%
-% \begin{variable}{\l_graphics_page_int}
+% \begin{variable}{page}
% The page to extract from a multi-page graphic file: used for |.pdf| files
% which may contain multiple pages.
% \end{variable}
%
-% \begin{variable}{\l_graphics_pagebox_tl}
+% \begin{variable}{pagebox}
% The nature of the page box setting used to determine the bounding box of
% material: used for |.pdf| files which feature multiple page box
-% specifications.
+% specifications. A choice from |art|, |bleed|, |crop|, |media|, |trim|.
% \end{variable}
%
-% \begin{variable}{\l_graphics_draft_bool}
+% \begin{variable}{draft}
% Switch to enable draft mode: graphics are read but not included when this is
% true.
% \end{variable}
%
+% \begin{variable}{type}
+% The type of graphic file beign included: if this key is not set, the
+% \emph{type} is determined from the file extension.
+% \end{variable}
+%
% \subsection{Including graphics}
%
-% \begin{function}{\graphics_include:n, \graphics_include:nn}
+% \begin{function}{\graphics_include:nn}
% \begin{syntax}
-% \cs{graphics_include:n} \Arg{file}
-% \cs{graphics_include:nn} \Arg{file} \Arg{type}
+% \cs{graphics_include:nn} \Args{keys} \Arg{file}
% \end{syntax}
-% Horizontal-mode commands which include the \meta{file} as an graphic
-% at the current location. The file \meta{type} is given explicitly in
-% the two-argument version, or is inferred from the file extension extracted
-% in the single-argument form. The exact graphic types supported depend upon
-% the driver in use.
+% Horizontal-mode command which includes the \meta{file} as an graphic
+% at the current location. The file \meta{type} may be given as one of the
+% \meta{keys}, or will otherwise be determined from file extension. The
+% \meta{keys} is used to pass settings as detailed above.
%
% Where the \meta{file} is not found and the \meta{type} is \emph{not}
% given, a search for possible graphic files is undertaken using the extensions
@@ -174,24 +184,45 @@
% \end{macrocode}
% \end{variable}
%
-% \subsection{Image feature support}
+% \subsection{Graphics keys}
%
% \begin{macro}
% {
-% \l_graphics_decodearray_tl ,
-% \l_graphics_interpolate_bool,
-% \l_graphics_page_int ,
-% \l_graphics_pagebox_tl
+% \l_@@_decodearray_str ,
+% \l__@@_draft_bool ,
+% \l_@@_interpolate_bool ,
+% \l_@@_page_int ,
+% \l_@@_pagebox_str ,
+% \l_@@_type_str
% }
% Keys which control features of graphics. The standard value of |pagebox|
-% set up here should match the default for the drivers themselves: in
-% the absence of any other setting the |cropbox| should be used.
+% set up here should match the default for the backends themselves: in
+% the absence of any other setting the |crop| should be used. Note that
+% the variable \cs{l_@@_pagebox_str} can be empty internally, as backends
+% which do not support |pagebox| are set up to clear it entirely.
% \begin{macrocode}
-\tl_new:N \l_graphics_decodearray_tl
-\tl_new:N \l_graphics_pagebox_tl
-\bool_new:N \l_graphics_interpolate_bool
-\tl_set:Nn \l_graphics_pagebox_tl { cropbox }
-\int_new:N \l_graphics_page_int
+\tl_new:N \l_@@_pagebox_str
+\keys_define:nn { graphics }
+ {
+ decodearray .str_set:N =
+ \l_@@_decodearray_str ,
+ draft .bool_set:N =
+ \l_@@_draft_bool ,
+ interpolate .bool_set:N =
+ \l_@@_interpolate_bool ,
+ pagebox .choices:nn =
+ { art , bleed , crop , media , trim }
+ {
+ \str_set:Nx \l_@@_pagebox_str
+ { \tl_use:N \l_keys_choice_tl box }
+ } ,
+ pagebox .initial:n =
+ crop ,
+ page .int_set:N =
+ \l_@@_page_int ,
+ type . str_set:N =
+ \l_@@_type_str
+ }
% \end{macrocode}
% \end{macro}
%
@@ -274,8 +305,8 @@
% \begin{macrocode}
\cs_new_protected:Npn \@@_extract_bb:n #1
{
- \int_compare:nNnTF \l_graphics_page_int > 0
- { \@@_extract_bb_auxi:Vn \l_graphics_page_int {#1} }
+ \int_compare:nNnTF \l_@@_page_int > 0
+ { \@@_extract_bb_auxi:Vn \l_@@_page_int {#1} }
{ \@@_extract_bb_auxii:nnn {#1} { } { } }
}
\cs_new_protected:Npn \@@_extract_bb_auxi:nn #1#2
@@ -283,9 +314,9 @@
\cs_generate_variant:Nn \@@_extract_bb_auxi:nn { Vn }
\cs_new_protected:Npn \@@_extract_bb_auxii:nnn #1#2#3
{
- \tl_if_empty:NTF \l_graphics_pagebox_tl
+ \tl_if_empty:NTF \l_@@_pagebox_str
{ \@@_extract_bb_auxiv:nnn }
- { \@@_extract_bb_auxiii:Vnnn \l_graphics_pagebox_tl }
+ { \@@_extract_bb_auxiii:Vnnn \l_@@_pagebox_str }
{#1} {#2} {#3}
}
\cs_new_protected:Npn \@@_extract_bb_auxiii:nnnn #1#2#3#4
@@ -395,13 +426,6 @@
% \end{macro}
% \end{macro}
%
-% \begin{variable}{\l_graphics_draft_bool}
-% Relevant to including graphics but not to reading them.
-% \begin{macrocode}
-\bool_new:N \l_graphics_draft_bool
-% \end{macrocode}
-% \end{variable}
-%
% \begin{variable}{\l_@@_final_name_str, \l_@@_full_name_str}
% The full name is as you'd expect the name including path and extension.
% The final name here reflects any conversions carried out by the backend,
@@ -454,33 +478,33 @@
% \end{macrocode}
% \end{variable}
%
-% \begin{macro}{\graphics_include:n}
+% \begin{macro}{\graphics_include:nm}
% \begin{macro}{\@@_include_search:n}
% \begin{macro}{\@@_include:}
-% \begin{macro}{\graphics_include:nn}
% \begin{macro}
% {
-% \@@_include_auxi:n, \@@_include_auxii:n,
+% \@@_include_auxi:n, \@@_include_auxi:e, \@@_include_auxii:n,
% \@@_include_auxiii:n, \@@_include_auxiv:n
% }
% Actually including an graphic is relatively straight-forward: most of the
-% work is done by the driver. We only have to deal with making sure the
+% work is done by the backend. We only have to deal with making sure the
% box has no apparent depth. Where the first given name is not found, we
% search based on extension only if the \meta{type} was not given. The one
% wrinkle is that we may have found a \texttt{.tex} file matching the file
% name stem: that's not what we want, so we have to filter out.
% \begin{macrocode}
-\cs_new_protected:Npn \graphics_include:n #1
+\cs_new_protected:Npn \graphics_include:nn #1#2
{
\group_begin:
+ \keys_set:nn { graphics } {#1}
\seq_set_eq:NN \l_file_search_path_seq \l_graphics_search_path_seq
- \file_get_full_name:nNTF {#1} \l_@@_full_name_str
+ \file_get_full_name:nNTF {#2} \l_@@_full_name_str
{
- \str_if_eq:eeTF { \l_@@_full_name_str } { #1 .tex }
- { \@@_include_search:n {#1} }
+ \str_if_eq:eeTF { \l_@@_full_name_str } { #2 .tex }
+ { \@@_include_search:n {#2} }
{ \@@_include: }
}
- { \@@_include_search:n {#1} }
+ { \@@_include_search:n {#2} }
\group_end:
}
\cs_new_protected:Npn \@@_include_search:n #1
@@ -495,25 +519,17 @@
}
\cs_new_protected:Npn \@@_include:
{
- \file_parse_full_name:VNNN \l_@@_full_name_str
- \l_@@_dir_str \l_@@_name_str \l_@@_ext_str
- \exp_args:Ne \@@_include_auxi:n
+ \str_if_empty:NTF \l_@@_type_str
{
- \exp_args:Ne \str_tail:n
- { \str_foldcase:V \l_@@_ext_str }
- }
- }
-\cs_new_protected:Npn \graphics_include:nn #1#2
- {
- \group_begin:
- \seq_set_eq:NN \l_file_search_path_seq \l_graphics_search_path_seq
- \file_get_full_name:nNTF {#1} \l_@@_full_name_str
- {
- \exp_args:Ne \@@_include_auxi:n
- { \str_foldcase:n {#1} }
- }
- { \msg_error:nnn { graphics } { graphic-not-found } {#1} }
- \group_end:
+ \file_parse_full_name:VNNN \l_@@_full_name_str
+ \l_@@_dir_str \l_@@_name_str \l_@@_ext_str
+ \@@_include_auxi:e
+ {
+ \exp_args:Ne \str_tail:n
+ { \str_foldcase:V \l_@@_ext_str }
+ }
+ }
+ { \@@_include_auxi:e { \l_@@_type_str } }
}
\cs_new_protected:Npn \@@_include_auxi:n #1
{
@@ -521,6 +537,7 @@
{ \tl_set:Nn \l_@@_internal_tl {#1} }
\exp_args:NV \@@_include_auxii:n \l_@@_internal_tl
}
+\cs_generate_variant:Nn \@@_include_auxi:n { e }
\cs_new_protected:Npn \@@_include_auxii:n #1
{
\mode_leave_vertical:
@@ -532,7 +549,7 @@
\seq_gput_right:NV \g_@@_record_seq \l_@@_final_name_str
\clist_if_exist:NT \@filelist
{ \exp_args:NV \@addtofilelist \l_@@_final_name_str }
- \bool_if:NTF \l_graphics_draft_bool
+ \bool_if:NTF \l_@@_draft_bool
{ \@@_include_auxiii:n }
{ \@@_include_auxiv:n }
{#1}
diff --git a/l3experimental/l3graphics/testfiles/m3graphics000.tlg b/l3experimental/l3graphics/testfiles/m3graphics000.tlg
index 21cdc7b2a..19a9d62fa 100644
--- a/l3experimental/l3graphics/testfiles/m3graphics000.tlg
+++ b/l3experimental/l3graphics/testfiles/m3graphics000.tlg
@@ -3,7 +3,7 @@ Don't change this file in any respect.
Author: Bruno Le Floch
(l3graphics.sty
Package: l3graphics ....-..-.. L3 Experimental graphics inclusion support
-\l_graphics_page_int=\count...
+\l__graphics_page_int=\count...
\l__graphics_llx_dim=\dimen...
\l__graphics_lly_dim=\dimen...
\l__graphics_urx_dim=\dimen...
More information about the latex3-commits
mailing list.