getter function for structure numbers from lua

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to the `tagpdf` package since the
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 this project uses date-based 'snapshot' version identifiers.
+## [Unreleased]
+
+### Added
+ - user lua functions ltx.tag.get_struct_num(), ltx.tag.get_struct_counter(), ltx.tag.get_struct_num_next()
+
 ## [2024-11-20]
 Version 0.99j
 

doc/tagpdf.tex

@@ -1171,14 +1171,19 @@ \subsubsection{Retrieving data} \label{sec:retrieve}
   it reverts to the parent number if a structure is closed. If only
   \pkg{tagpdf-base} is loaded nesting of structure is not tracked and
   so the command gives back the number of the last structure that has
-  been created.
+  been created. In luatex this number can also be retrieved with the 
+  lua function \texttt{ltx.tag.get_struct_num()}.  
 
 \item \verb+struct_counter+: This returns a number and works also if
   only \pkg{tagpdf-base} has been loaded. It gives back the state of
   the absolute structure counter and so the number of the last structure
   that has been created. This can be used to detect if in a piece of
   code there are structure commands. Be aware that this is a \LaTeX{}
   counter and so is reset in some places.
+  In luatex this number can also be retrieved with the 
+  lua function \texttt{ltx.tag.get_struct_counter()}. The number of the next
+  structure to be created is then \texttt{ltx.tag.get_struct_counter()} increased by
+  one), this can also be retrieved with the function \texttt{ltx.tag.get_struct_num_next()}.
 
 \item \verb+mc_counter+: This returns a number and works also if only
   \pkg{tagpdf-base} has been loaded. It gives back the state of the

tagpdf-backend.dtx

@@ -234,6 +234,9 @@ functions
  ltx.@@.trace.show_prop: shows a prop
  ltx.@@.trace.log
  ltx.@@.trace.showspaces : boolean
+
+ ltx.tag.get_structnum: number, shows the current structure number
+ ltx.tag.get_structnum_next: number, shows the next structure number 
 --]]
 
 %    \end{macrocode}
@@ -309,6 +312,7 @@ local regular_disc = 3
 % Now we setup the main table structure. ltx is used by other latex code too!
 %    \begin{macrocode}
 ltx             = ltx        or { }
+ltx.tag         = ltx.tag       or { } -- user commands
 ltx.@@          = ltx.@@        or { }
 ltx.@@.mc       = ltx.@@.mc     or  { } -- mc data
 ltx.@@.struct   = ltx.@@.struct or  { } -- struct data
@@ -321,6 +325,35 @@ ltx.@@.trace    = ltx.@@.trace  or  { } -- show commands
 ltx.@@.func     = ltx.@@.func   or  { } -- functions
 ltx.@@.conf     = ltx.@@.conf   or  { } -- configuration variables
 %    \end{macrocode}
+%
+% \section{User commands to access data}
+% Code like the one in luamml will have to access the current state in some places.
+
+% \begin{macro}{\}
+%    \begin{macrocode}
+local @@_get_struct_num = 
+ function()
+  local a = token.get_macro("g__tag_struct_stack_current_tl")
+  return a
+ end
+
+local @@_get_struct_counter = 
+ function()
+  local a = tex.getcount("c@g_@@_struct_abs_int")
+  return a
+ end
+
+local @@_get_struct_num_next = 
+ function()
+  local a = tex.getcount("c@g_@@_struct_abs_int") + 1
+  return a
+ end
+
+ltx.tag.get_struct_num = @@_get_struct_num
+ltx.tag.get_struct_counter = @@_get_struct_counter
+ltx.tag.get_struct_num_next = @@_get_struct_num_next
+%    \end{macrocode}
+% \end{macro}
 % \section{Logging functions}
 %
 % \begin{macro}{@@_log,ltx.@@.trace.log}

testfiles-luatex/getstructnum.lvt

@@ -0,0 +1,38 @@
+\ExplSyntaxOn
+\debug_on:n { check-declarations , deprecation }
+\msg_redirect_module:nnn { pdf } { none } { warning }
+\ExplSyntaxOff
+\DocumentMetadata{testphase=phase-III}
+\input{regression-test}
+
+\documentclass{article}
+\ExplSyntaxOn
+\cs_set_eq:NN\tagget\tag_get:n
+\ExplSyntaxOff
+\begin{document}
+\START\showoutput
+
+\section{blub}
+blub
+
+blub 
+\emph{
+  \tagget{struct_num}, \tagget{struct_counter}  
+  \directlua
+    {texio.write_nl
+     ("term and log",
+      " current structcounter "..ltx.tag.get_struct_counter(),
+      " current structnum "    ..ltx.tag.get_struct_num(),
+      " next struct "          ..ltx.tag.get_struct_num_next()           
+     )}
+   }    
+xxx  
+  \tagget{struct_num}, \tagget{struct_counter}  
+  \directlua
+    {texio.write_nl
+     ("term and log",
+      " current structcounter "..ltx.tag.get_struct_counter(),
+      " current structnum "    ..ltx.tag.get_struct_num(),
+      " next struct "          ..ltx.tag.get_struct_num_next()           
+     )}  
+\end{document}

testfiles-luatex/getstructnum.tlg

@@ -0,0 +1,25 @@
+This is a generated file for the l3build validation system.
+Don't change this file in any respect.
+ current structcounter 12
+ current structnum 12
+ next struct 13
+ current structcounter 12
+ current structnum 11
+ next struct 13
+[1
+] (getstructnum.aux)
+Package tagpdf Info: Finalizing the tagging structure:
+(tagpdf)             Writing out ~12 structure objects
+(tagpdf)             with ~9 'MC' leaf nodes.
+(tagpdf)             Be patient if there are lots of objects!
+Package tagpdf Info: writing ParentTree
+Package tagpdf Info: writing IDTree
+Package tagpdf Info: writing RoleMap
+Package tagpdf Info: writing ClassMap
+Package tagpdf Info: writing NameSpaces
+Package tagpdf Info: writing StructElems
+Package tagpdf Info: writing Root
+***************
+Compilation 1 of test file completed with exit status 0
+Compilation 2 of test file completed with exit status 0
+Compilation 3 of test file completed with exit status 0