\NeedsTeXFormat{LaTeX2e}[1994/12/01]
\ProvidesPackage{filedate}[2013/03/26 v0.41 check file dates (UL)]

%% Copyright (C) 2012 2013 Uwe Lueck,
%% http://www.contact-ednotes.sty.de.vu
%% -- author-maintained in the sense of LPPL below --
%%
%% This file can be redistributed and/or modified under
%% the terms of the LaTeX Project Public License; either
%% version 1.3c of the License, or any later version.
%% The latest version of this license is in
%%     http://www.latex-project.org/lppl.txt
%% We did our best to help you, but there is NO WARRANTY.
%%
%% Please report bugs, problems, and suggestions via
%%
%%   http://www.contact-ednotes.sty.de.vu
%%
%% % \filbreak                       %% 2012/11/10 rm. 2013/03/25
%%  === The 'readprov' Package    ===
%% \label{sec:readprov}
% \RequirePackage{readprov}
%% ---is required for \[|\ReadInfoDate{<file>}|\quad 
%% \mbox{and}\quad |\ReadCheckDateOf{<file>}{<date>}|\] 
%% %% <- <date>, \[...\] 2012/10/25
%% % \hyperref[sec:readinfo]{below} 
%% (sections~\ref{sec:readinfo} and \ref{sec:readcheck})
%% % below
%% only. 
%% Please care for providing \ctanpkgdref{readprov} %% href 2013/03/25
%% on your own if you need that.
%%
%%  === Providing Dates for Comparisons      ===    %% 2013/03/24
%% ==== Accessing ``Info Date"               ====
%% \label{sec:readinfo}
%% |\theinfodateof{<file>}| will expand to the first ``word" of the 
%% `\Provides'\code{...} entry, provided that has been read before:
\newcommand*{\theinfodateof}[1]{%
    \@ifundefined{ver@#1}{unknown}{%
         \expandafter\expandafter\expandafter
             \FD@firstword\csname ver@#1\endcsname\@gobble{} \@nil}}
\def\FD@firstword#1 #2\@nil{#1}
%% This avoids the `\relax' that `\UseDateOf' from \ctanpkgref{readprov}
%% currently adds (which doesn't harm in printing but is bad for comparing).
%%
%% |\LoadInfoDateOf{<file>}| sets |\theinfodate| to the first word of 
%% what is in the `\Provides' instruction of <file>, provided that info 
%% has been input. So far, you must care for yourself that this works.
%% % The purpose of this kind of actions is to refer to a ``type'' of 
%% % comparisons (with `\CheckDateGiven') for a multiplicity of files.
\newcommand*{\LoadInfoDateOf}[1]{%
    \edef\theinfodate{\theinfodateof{#1}}}
%% |\ReadInfoDateOf{<file>}| additionally inputs the info before:            
\newcommand*{\ReadInfoDateOf}[1]{%
    \ReadFileInfos{#1}\LoadInfoDateOf{#1}}
%% TODO provide automatically.
%%
%% ==== Accessing \cs{pdffilemoddate}        ====
%% \label{sec:pdfmod}
%% |\pdffilemoddate{<file>}| in the first instance is a \ctanpkgref{pdftex}
%% primitive. With \LuaTeX, 
%% \ctanpkgdref{pdftexcmds} provides it.            %% d 2013/03/25
%% Currently, you must care for this yourself before loading the 
%% present package. I recommend the 
%% \ctanpkgdref{filemod} documentation for          %% d 2013/03/25
%% details about \cs{pdffilemoddate}.
%%
%% %% rm. 2013/03/24:
%% % Otherwise, (with \XeLaTeX) the modification date may be obtained 
%% % by a (shell) script---the next definitions do \emph{not} deal with 
%% % the latter situation. Testing against ``today" 
%% % (|\rawtoday| in Section~\ref{sec:rawtoday})
%% % may be another alternative.
%%
%% |\thepdfmoddateof{<file>}| expands to the modification date 
%% (eight digits separated by two slashes) if `\pdffilemoddate' 
%% is available. Otherwise, we are trying to inform about 
%% unavailability:
\ifx\pdffilemoddate\@undefined
    \newcommand*{\thepdfmoddateof}{%
        \string\pdffilemoddate\space unavailable.}
\else
    \newcommand*{\thepdfmoddateof}[1]{%
        \expandafter \FD@pdftexdate \pdffilemoddate{#1}\@nil}
    \expandafter \def \expandafter
        \FD@pdftexdate\string D:#1#2#3#4#5#6#7#8#9\@nil{%
            #1#2#3#4/#5#6/#7#8}
%% ---cf.~Will \ctanpkgauref{robertson}{Robertson}'s suggestion dating from 2010 on 
%% \httpref{stackoverflow.com/questions/2118972/latex-command-for-last-modified}{%
%% \urlfmt{stackoverflow.com}} in another discussion of accessing modification dates, 
%% including use of scripts.
%% `\string D' deals with the fact that `\pdffilemoddate' returns 
%% % in                         %% rm. 2013/03/24
%% ``other" character tokens.
\fi
%% The modification date of <file> according to `\pdffilemoddate'
%% will be available as `\thepdffilemoddate' after 
%% `ReadPDFfileModDateOf{<file>}', see \secref{short-refdates}.
%%
%% ==== \cs{rawtoday}                        ====
%% \label{sec:rawtoday}
%% % Enabling `\CheckDateOf{<file>}{\rawtoday}':
%% |\rawtoday| accesses ``today"'s date as eight digits separated 
%% by two slashes (`yyyy/mm/dd'):
\newcommand*{\rawtoday}{%
    \the\year/\two@digits{\the\month}/\two@digits{\the\day}}
%%
%%  === Comparing Basically                  ===
%% \label{sec:readcheck}
%% |\CheckDateOf{<file>}{<ref-date>}| compares <file>'s \strong{info} date with 
%% the \strong{reference} date <ref-date>:
\newcommand*{\CheckDateOf}[2]{%
%% We provide a check that does not affect the order with 
%% \ctanpkgdref{myfilist}.                                  %% 2013/03/25
%     \ReadFileInfos{#1}%
%% The date according to `\Provides' will be accessible as |\theinfodate|:
    \LoadInfoDateOf{#1}%
%     \show\theinfodate
    \ReadPDFmodDateOf{#1}%
    \edef\FD@therefdate{#2}%
%     \show\FD@therefdate
    \ifx\theinfodate\FD@therefdate
        \FD@datesequal{#1}%
    \else
        \FD@datesdiff{#1}%
    \fi}
%% The \strong{reference} date may be either (i)~\emph{today} as accessed 
%% by `\rawtoday' (\secref{rawtoday}), (ii)~the \emph{modification} date as accessed 
%% by `\pdffilemoddate' (\secref{pdfmod}), (iii)~something \emph{else} relevant, 
%% e.g., a modification date determined and inserted by a shell script.
%% %% <- added 2013/03/24
%% 
%% |\ReadCheckDateOf{<file>}{<date>}| \ prepends \ |\ReadFileInfos{<file>}|
%% from the \ctanpkgref{readprov} package (cf. Section~\ref{sec:readprov}), 
%% in order to ensure that the \strong{info} date is known:
\newcommand*{\ReadCheckDateOf}[1]{%
    \ReadFileInfos{#1}\CheckDateOf{#1}}
%% TODO provide automatically.
%% 
%%  === Reporting Styles                     === %% subsections 2013/03/24
%% ==== Same Dates                           ====
%% By default, there is no report about comparisons finding \strong{equality}.
\let\FD@datesequal\@gobble
%% % We do not want to disturb `\listfiles' with \ctanpkgref{myfilist}. 
%% %% <- rm. 2012/10/25
%% |\EqualityMessages| changes this to screen and log messages: 
\newcommand*{\EqualityMessages}{\let\FD@datesequal\FD@equalmess}
\def\FD@equalmess#1{\message{ + #1 passed date check + }}
\def\FD@errdatesdiff#1{%
    \PackageError{filedate}{%
        \FD@infodate{#1}\FD@refdate}{%      %% \fd@refdate 2012/10/19
        Fix that!}}
%% |\FD@infodate{<file>}| might be used to change the current 
%% presentation of the ``info date:"
\def\FD@infodate#1{% 
    #1 has \string\Provides... date \theinfodate\space}
%% TODO here |\theinfodate| could be replaced by 
%% |\theinfodateof{#1}|, there is no essential application of 
%% `\theinfodate' currently.
%%
%% ==== Differing Dates                      ====
%% After |\DatesDiffErrors|, date \strong{differences} 
%% are reportet ``drastically" by `\PackageError':
\newcommand*{\DatesDiffErrors}{\let\FD@datesdiff\FD@errdatesdiff}
%% This is the default:
\DatesDiffErrors
%% After |\DatesDiffNotices|, date differences are reported by 
%% %% <- told -> reported  2012/10/19
%% `\typeout':
\newcommand*{\DatesDiffNotices}{\let\FD@datesdiff\FD@notedatesdiff}
\def\FD@notedatesdiff#1{\def\MessageBreak{^^J}%   %% added 2012/10/24
                        {\typeout{\FD@infodate{#1}%
                                  \FD@refdate}}}  %% added 2012/10/19
%% v0.3 adds |\DatesDiffWarnings| to get more salient reports of 
%% date differences by `\PackageWarningNoLine':
\newcommand*{\DatesDiffWarnings}{\let\FD@datesdiff\FD@warndatesdiff}
\def\FD@warndatesdiff#1{%
    \PackageWarningNoLine{filedate}%
                         {\FD@infodate{#1}\FD@refdate}}
%% ==== Kinds of Reference Dates             ====
%% When the reference date is `\pdffilemoddate', the report about 
%% a comparison may call it a ``modification date". 
%% But when the reference date is ``today", it may not be a 
%% ``modification date". Otherwise, it depends ...
%% (See \secref{readcheck} for kinds of reference dates.)
%% 
%% After |\ModDates|, reference dates are called ``modification'' dates: 
\newcommand*{\ModDates}{\let\FD@refdate\FD@moddate}
\def\FD@moddate{\MessageBreak vs. modification date \FD@therefdate}
%% After |\SomeDates|, the type of reference dates is not specified. 
%% This is more accurate when the info date is compared with |\rawtoday|.
\newcommand*{\SomeDates}{\let\FD@refdate\FD@somedate}
\def\FD@somedate{\MessageBreak vs. \FD@therefdate}
%% That's the default:
\SomeDates
%%
%%  === Shorthands                           ===
%% %% mod. again 2013/03/25
%% We may want to compare \emph{info} with \emph{reference} dates for 
%% many files. But when the \emph{reference} date is `\pdffilemoddate' 
%% for many files
%% (probably the most frequent application, see \secref{pdfmod}), 
%% we don't want to state this explicitly for each 
%% file---\secref{short-refdates}---neither 
%% for other kinds of reference dates.
%% 
%% As to enumerating \emph{file names}, the 'filesdo' package 
%% from the \ctanpkgdref{commado} bundle should help 
%% (combinations of base names and extensions, 
%%  see \secref{demo-here};                             %% 2013/03/25
%%  TODO: shorthands using 'filesdo' could be defined 
%%  in the present package).
%%
%% The files <in-file> whose dates we want to check may be just 
%% the same that some <reading-file> tries to `\input'.
%% It may me helpful if those input commands trigger the 
%% file consistency check without a need to demand this explicitly 
%% for each file---the section on ``automatic immediate checking"
%% (\secref{auto-check}) aims at this. 
%% 
%% ==== Kinds of Reference Dates             ====
%% \label{sec:short-refdates}
%% |\ReadPDFmodDateOf{<file>}| enables
%% \[|\CheckDateOf{<file>}{\thepdfmoddate}|\] 
%% by setting |\thepdfmoddate|:
\newcommand*{\ReadPDFmodDateOf}[1]{%
    \edef\thepdfmoddate{\thepdfmoddateof{#1}}}
%% % The purpose of this section is to control the reference date 
%% % without changing commands with <file> arguments. 
%% After a single |\UseReferenceDate{<date>}| all ensuing 
%% \[|\CheckDateOfGiven{<file>}|\] compare 
%% % `\theinfodateof{<file>}'
%% <file>'s ``info date"
%% with 
%% % |\thedategiven|. 
%% <date>.
%% % <date> 
%% The latter 
%% may be an explicit
%% \[<4-digits>/<2-digits>/<2-digits>\quad 
%% (`yyyy/mm/dd')\]---a script might insert it---, 
%% `\rawtoday', or `\thepdfmoddate'.
%% \ctanpkgdref{adhocfilelist} v0.7 (with option \strong{\code{-c}}) 
%% is such a script, a shell script generating a ``\TeX\ script", 
%% providing the file modification date according to Unix/Linux.
\newcommand*{\UseReferenceDate}{\def\thedategiven}
\newcommand*{\CheckDateOfGiven}[1]{\CheckDateOf{#1}{\thedategiven}}
%%
%% %%% *** Clarifying Reference Type in Reports ***
%% |\CheckDateOfPDFmod{<file>}| compares the ``info date" 
%% with the modification date according to `\pdffilemoddate', 
%% and in reporting a difference the modification 
%% date it is called a ``modification date" indeed:
\newcommand*{\CheckDateOfPDFmod}[1]{%
    \begingroup
        \ModDates
        \CheckDateOf{#1}{\thepdfmoddate}%
    \endgroup}
%% |\CheckDateOfToday{<file>}| checks if the `\Provides' date is today's, 
%% and the report of a difference somewhat emphasizes that this may not 
%% be a \emph{modification} date. 
%% (It may be a \emph{substitute} for a modification date when you 
%%  know that the file was modified ``today".)
\newcommand*{\CheckDateOfToday}[1]{%
    \begingroup
        \def\FD@refdate{%
            \MessageBreak which is not today}%
        \CheckDateOf{#1}{\rawtoday}%
    \endgroup}
%% 
%% ==== Automatic Immediate Checking         ==== 
%% \label{sec:auto-check}
%% |\FileDateAutoChecks| modifies the \qtdcode{&\Provides...}
%% commands internally so that they check their date with 
%% with the file's modification date according to 
%% |\pdffilemoddate|---this choice might be queried (TODO).
%% The modification may be undone by |\NoFileDateAutoChecks|
%% so that the \qtdcode{&\Provides...} commands get their 
%% original functionality (only) again. This will even work 
%% with \ctanpkgref{readprov} v0.4.
%% 
%% Actually, \LaTeX's internal `\@pr@videpackage' and 
%% `\@profidesfile' are used as hooks. Their original meanings 
%% are stored so they can be regained by \qtd{&\NoFile...}:
\let\FD@@provpkg\@pr@videpackage
\def\FD@provpkg[#1]{\FD@@provpkg[#1]%
                    \CheckDateOfPDFmod{\@currname.\@currext}}
\let\FD@@provfile\@providesfile
\def\FD@provfile#1[#2]{\FD@@provfile{#1}[#2]%
                       \CheckDateOfPDFmod{#1}}
%% |\FileDateAutoChecks*| in addition to `\FileDateAutoChecks'
%% checks the main file's info date, 
%% assuming the main file is `\jobname.tex' 
%% (TODO):                              %% 2013/03/25 cf. \@iinput
\newcommand*{\FileDateAutoChecks}{%
    \@ifstar{{\FD@check@pdf@job\FD@autochecks}\FD@autochecks}%
                                              \FD@autochecks} 
%% |\FD@check@pdf@job| is introduced in v0.41 for the 
%% ``restricted" automatic checks below.
\newcommand*{\FD@check@pdf@job}{\CheckDateOfPDFmod{\jobname.tex}}
\newcommand*{\FD@autochecks}{\let\@pr@videpackage\FD@provpkg
                             \let\@providesfile\FD@provfile}
\newcommand*{\NoFileDateAutoChecks}{\let\@pr@videpackage\FD@@provpkg
                                    \let\@providesfile  \FD@@provfile}
%%
%% However, see \secref{auto-level} for \strong{problems}
%% of the previous idea 
%% (unless using \ctanpkgdref{fileinfo}, i.e., 'readprov' or even 'myfilist').
%%
%% \pagebreak                                       %% 2013/03/25
%% ==== Level-Restricted Automatic Checking  ====   %% 2013/03/25
%% \label{sec:auto-level}
%% The present package is made to ensure ``date consistency" 
%% of files that the user maintains/edits. By contrast, 
%% date consistency cannot be expected for \LaTeX\ package 
%% files that were generated by \ctanpkgdref{docstrip} 
%% (many days after the `.dtx' source was released).
%% No date consistency checks should be applied to such files. 
%% (The ``criticism" of the present section does not apply to 
%%  usage with \ctanpkgref{fileinfo}, and the commands presented 
%%  here \emph{disable} 'fileinfo', so don't use them with 'fileinfo'.)
%% 
%% The problem with `\FileDateAutoChecks' (\secref{auto-check}) is, 
%% e.g., that a chapter file for a book that is `\include'd by 
%% the master file may trigger loading a font definition file 
%% (`.fd')---that is not date-consistent, though the test is 
%% applied to it. We now aim at checking only those files 
%% that are input by the file that contains the call, 
%% not to files that are input indirectly.
%% We use `\InputIfFileExists' as a hook for this. 
%% This should affect \emph{\LaTeX} user commands for file inclusion,
%% even for (the user's) packages and class files. 
%% It does \emph{not} affect the version of `\input' without braces.
%% The commands for this purpose are |\FileDateLevelChecks|, 
%% |\FileDateLevelChecks*|, and |\NoFileDateLevelChecks|
%% (replacing `Auto' by `Level' for analogy to the commands 
%%  of \secref{auto-check}).
%% 
%% The implementation is somewhat recursive, or ``counter-recursive"?
\def\FD@level@provpkg   [#1]{\FD@provpkg[#1]%
                             \NoFileDateLevelChecks}
\def\FD@level@provfile#1[#2]{\FD@provfile{#1}[#2]%
                             \NoFileDateLevelChecks}
%% |\FD@userchecks@| is introduced for \secref{auto-user}:
\newcommand*{\FD@userchecks@}{\let\@pr@videpackage\FD@level@provpkg
                              \let\@providesfile\FD@level@provfile}
\newcommand*{\FD@levelchecks}{\FD@userchecks@
                              \let\InputIfFileExists\FD@input@if@f@ex}
\let\FD@@input@if@f@ex\InputIfFileExists
\newcommand{\FD@input@if@f@ex}[3]{\FD@@input@if@f@ex{#1}{#2}{#3}%
                                  \FD@levelchecks}
\newcommand*{\FileDateLevelChecks}{%
    \@ifstar{\CheckDateOfPDFmod{\jobname.tex}\FD@levelchecks}%
                                             \FD@levelchecks} 
\newcommand*{\NoFileDateLevelChecks}{%
    \NoFileDateAutoChecks \let\InputIfFileExists\FD@@input@if@f@ex}
%% Section \ref{sec:auto-user} introduces another idea 
%% to avoid checking of \LaTeX\ package files.
%%
%% ==== User-Restricted Automatic Checking   ====   %% 2013/03/26
%% \label{sec:auto-user}
%% Another idea to avoid checking of \LaTeX\ package files 
%% while checking `\input' files automatically are 
%% |\FileDateUserChecks| and |\FileDateUserChecks*|
%% only affecting user transclusion commands %%% such as 
%% `\include{<file>}' and `\input{<file>}' while allowing 
%% nesting, i.e., e.g., even an `\input{<indir>}' in an 
%% `\include'd file is checked automatically. 
%% (See \secref{auto-level} if you do not remember what is 
%%  bad with \secref{auto-check}.)
\let\FD@@iinput\@iinput \let\FD@@include\@include
%% Using definitions from above:
\newcommand*{\FD@userchecks}{%
%% `\@iinput' is \LaTeX's internal behind `\input':
    \def\@iinput##1{%
        \FD@userchecks@\FD@@iinput{##1}\NoFileDateAutoChecks}%
%% `\@include' is \LaTeX's internal behind `\include'. 
%% Its argument is limited by a space:
    \def\@include##1 {%
        \FD@userchecks@\FD@@include##1 \NoFileDateAutoChecks}}
%% Temporary switching off `\FD@provpkg' and `\FD@provfile' 
%% is doubled to deal with files that don't have a 
%% `\Provides' entry. 
\newcommand*{\FileDateUserChecks}{%
    \@ifstar{\FD@check@pdf@job\FD@userchecks}\FD@userchecks} 
\newcommand*{\NoFileDateUserChecks}{%
    \let\@iinput\FD@@iinput \let\@include\FD@@include}
%% TODO `\usepackage', `\documentclass'?
%%
%%  === Leaving the Package File ===
\endinput
%% \pagebreak                                       %% 2013/03/25
%%  === VERSION HISTORY ===

v0.1   2012/10/15   core try, bad
v0.2   2012/10/16   code for first release 
       2012/10/17   reordering, correcting documentation
v0.21  2012/10/19   \fd@datekind\@tempb -> \fd@refdate,
                    \fd@refdate with \DatesDiffNotices! (bug)
                    \@tempb -> \fd@therefdate; doc. mod.s
v0.3   2012/10/24   \MessageBreak fix, \DatesDiffWarnings
       2012/10/25   doc.: add <date> in sec:readprov, 
                    rm. remark on \fd@datesequal, 
                    mod. text on \DatesDiffWarnings,
                    -- -> --- before `a script might'
v0.4   2012/11/10   \fd@ -> \FD@, doc. v0.7 -> v0.3, v0.21, 
                    \filbreak; code for \...AutoChecks
       2012/11/11   doc. another \filbreak, documenenting
                    \...AutoChecks, \...AutoChecks*
v0.41  2013/03/24   doc. restructured and extended
       2013/03/25   ... continued; section with \FileDateLevelChecks 
                    etc., \@ifstar without braces; 
                    doc. automatical ("archaic") -> automatic, 
                    reducing numbers of lines
       2013/03/26   \FileDateUserChecks etc., \FD@check@pdf@job