\NeedsTeXFormat{LaTeX2e}[1994/12/01]
\ProvidesPackage{filedate}[2012/10/19 v0.21 check file dates (UL)]

%% Copyright (C) 2012 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
%%
%% === The \ctanpkgref{readprov} Package    ===
%% \label{sec:readprov}
% \RequirePackage{readprov}
%% ---is required for |\ReadInfoDate{<file>}|
%% and |\ReadCheckDateOf{<file>}| 
%% % \hyperref[sec:readinfo]{below} 
%% (sections~\ref{sec:readinfo} and \ref{sec:readcheck})
%% % below
%% only. 
%% Please care for providing it on your own if you need that.
%%
%% \pagebreak
%% === 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}        ===
%% |\pdffilemoddate{<file>}| in the first instance is a \ctanpkgref{pdftex}
%% primitive. With \LuaTeX, \ctanpkgref{pdftexcmds} provides it. 
%% Currently, you must care for this yourself before loading the 
%% present package. I recommend the \ctanpkgref{filemod} documentation for 
%% details about \cs{pdffilemoddate}.
%%
%% 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 ``other" 
%% character tokens.
\fi
%%
%% === \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                            ===
%% \label{sec:readcheck}
%% |\CheckDateOf{<file>}{<date>}| compares <file>'s info date with 
%% <date>:
\newcommand*{\CheckDateOf}[2]{%
%% We provide a check that does not affect the order with \ctanpkgref{myfilist}.
%     \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}
%% |\ReadCheckDateOf{<file>}{<date>}| prepends |\ReadFileInfos{<file>}|
%% from the \ctanpkgref{readprov} package (cf. Section~\ref{sec:readprov}):
\newcommand*{\ReadCheckDateOf}[1]{%
    \ReadFileInfos{#1}\CheckDateOf{#1}}
%% TODO provide automatically.
%% 
%% \pagebreak
%% === Reporting Styles                     ===
%% By default, there is no report about comparisons finding equality.
\let\fd@datesequal\@gobble
%% We do not want to disturb `\listfiles' with \ctanpkgref{myfilist}. 
%% |\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.
%%
%% After |\DatesDiffErrors|, date 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{\typeout{\fd@infodate{#1}%
                                 \fd@refdate}}    %% added 2012/10/19
%% 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
%%
%% === Reference Date ``Types"              ===
%% |\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'.
%% \ctanpkgref{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}
%% 
%%
%% TODO single check commands for comma-separated list of files, 
%% (\ctanpkgref{dowith}) 
%% automatic tests by `\ReadFileInfos' etc. (\ctanpkgref{fileinfo}).
%%
%% === Leaving the Package File ===
\endinput
%%
%% === 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
