% pdfannotations.sty
% Provides the pdfannotations package for annotating PDF slides with LaTeX elements.
\ProvidesPackage{pdfannotations}[2023/11/22 v3.1 PDF Annotations Package]

% Essential Packages
% ------------------

% Graphics and design
\RequirePackage{graphicx} % For including graphics
\RequirePackage{xcolor} % For defining custom colors
\RequirePackage{listings} % For code formatting in documents

% LaTeX3 Programming Syntax
% -------------------------
\RequirePackage{xparse} % For defining LaTeX commands
\RequirePackage{expl3} % For LaTeX3 syntax

% PDF Handling and Hyperlinking
% -----------------------------
\RequirePackage[bookmarksopen=true, colorlinks=true, linkcolor=blue, citecolor=blue, urlcolor=blue]{hyperref} % For hyperlinking
\RequirePackage{pdfpages} % For including PDF pages

% Custom Colors Definition
% ------------------------
% These colors are used for syntax highlighting and other styling purposes.
\definecolor{codegreen}{rgb}{0,0.6,0}
\definecolor{codegray}{rgb}{0.5,0.5,0.5}
\definecolor{codepurple}{rgb}{0.58,0,0.82}
\definecolor{backcolour}{rgb}{0.95,0.95,0.92}
\definecolor{codeblue}{rgb}{0.25,0.5,0.5}

% Python Code Style Configuration
% -------------------------------
% This style is applied for Python code listings.
\lstdefinestyle{pythonstyle}{
  language=Python,
  backgroundcolor=\color{backcolour},
  commentstyle=\color{codegreen},
  keywordstyle=\color{codeblue},
  numberstyle=\tiny\color{codegray},
  stringstyle=\color{codepurple},
  basicstyle=\ttfamily\small,
  breakatwhitespace=false,         
  breaklines=true,                 
  captionpos=b,                    
  keepspaces=true,                 
  numbers=left,                    
  numbersep=5pt,                  
  showspaces=false,                
  showstringspaces=false,
  showtabs=false,                  
  tabsize=2
}
\lstset{style=pythonstyle}

% LaTeX3 Syntax Activation
\ExplSyntaxOn

% Internal Variables and Counters
% -------------------------------
\newcounter{currentslide}
\newcounter{totalpdfpages}
\newcounter{currentpdfindex}
\newcommand{\currentpdfname}{}
\prop_new:N \g_slide_annotations_prop
\prop_new:N \g_interludes_prop
\tl_new:N \l_slideinterlude_content_tl
\tl_new:N \l_slideannotate_content_tl
\prop_new:N \g_suppressed_slides_prop
\int_new:N \g_max_interludes_int
\seq_new:N \g_pdf_pages_seq
\seq_new:N \g_pdf_files_seq
\fp_new:N \g_pdf_max_width_fp

% Setting the Global Variable for Maximum PDF Width
\fp_gset:Nn \g_pdf_max_width_fp { \dim_to_fp:n {\PDFMaxWidth} }

% Log Function for Sequence Contents
\cs_new_protected:Nn \__log_seq_contents:n
{
  \seq_map_inline:Nn #1
    {
      \iow_log:n { PDFAnnotations:~--~\tl_to_str:n {#1} }
    }
}

% Populate PDF Sequence from User-Defined List
\clist_if_empty:NTF \PDFList
 {
  \iow_log:n { PDFAnnotations:~\PDFList~is~genuinely~empty. }
  \seq_clear:N \g_pdf_files_seq
  \seq_clear:N \g_pdf_pages_seq
 }
 {
  \iow_log:n { PDFAnnotations:~\PDFList~contains~items,~processing. }
  \clist_map_inline:Nn \PDFList
   {
    \tl_set:Nn \l_tmpa_tl {#1}
    \tl_trim_spaces:N \l_tmpa_tl
    \tl_if_empty:NF \l_tmpa_tl
     {
      \seq_gput_right:Nx \g_pdf_files_seq {\exp_args:No \detokenize \l_tmpa_tl}
      \iow_log:n { PDFAnnotations:~added~file:~\tl_to_str:n {\l_tmpa_tl} }
     }
   }
  \iow_log:n { PDFAnnotations:~\g_pdf_files_seq~final~contents: }
  \__log_seq_contents:n \g_pdf_files_seq
 }

% Auto-Detection of PDF Pages
\cs_new_protected:Nn \__get_pdf_pages:n
{
  \

iow_log:n { PDFAnnotations:~getting~page~count~for~file:~#1 }
  \exp_args:Nx \pdfximage {#1}
  \seq_gput_right:Nx \g_pdf_pages_seq {\the\pdflastximagepages}
  \iow_log:n { PDFAnnotations:~file~#1~has~\the\pdflastximagepages~pages. }
}

% Process Each File in the Sequence
\seq_map_inline:Nn \g_pdf_files_seq
{
  \iow_log:n { PDFAnnotations:~processing~file:~#1 }
  \__get_pdf_pages:n {#1}
  \iow_log:n { PDFAnnotations:~processed~file:~#1 }
}

\iow_log:n { PDFAnnotations:~\g_pdf_files_seq~final~contents: }
\__log_seq_contents:n \g_pdf_files_seq
\iow_log:n { PDFAnnotations:~\g_pdf_pages_seq~final~contents: }
\__log_seq_contents:n \g_pdf_pages_seq

\ExplSyntaxOff

% End of pdfannotations.sty