directory-tree.dtx

% \iffalse meta-comment
%
% Copyright (C) 2015 by Peter Brantsch
% (https://github.com/brantsch/lualatex-directory-tree)
% -------------------------------------------------------
% 
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.2
% of this license or (at your option) any later version.
% The latest version of this license is in:
%
%    http://www.latex-project.org/lppl.txt
%
% and version 1.2 or later is part of all distributions of LaTeX 
% version 1999/12/01 or later.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{skeleton.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{directory-tree}
%<*package>
    [2015/07/17 v0.1 directory-tree package]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{directory-tree}[2015/07/17]
\usepackage{charter}
\usepackage{listings}
\usepackage[font=it,labelfont=bf]{caption}
\usepackage[colorlinks]{hyperref}
\lstset{numberstyle=\footnotesize,basicstyle=\small\ttfamily,language=[5.2]Lua,breaklines,frame=l,numbers=left,float=t,stepnumber=5}
\renewcommand{\ttdefault}{lmtt}
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{directory-tree.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v0.1}{2015/07/17}{Initial version}
%
% \GetFileInfo{directory-tree.sty}
%
% \DoNotIndex{\newcommand,\newenvironment}
% 
%
% \title{The \textsf{directory-tree} package\thanks{This document
%   corresponds to \textsf{directory-tree}~\fileversion, dated \filedate.}}
% \author{Peter Brantsch \\ \url{https://github.com/brantsch/lualatex-directory-tree}}
%
% \maketitle
%
% \section{Introduction}
%
% This package draws directory trees using TikZ and the Lua filesystem library.
% It can thus only work with Lua\LaTeX.
%
% \section{Usage}
%
% \subsection{Drawing the tree}
% \DescribeMacro{\directoryTree\oarg{n}\marg{p}}
% This macro draws a directory tree with the path \meta{p} given as its argument at the root.
% It creates a TikZ picture to accomplish this.
%
% The optional \meta{n} argument is used to define a name for saving (and later retrieval) of the list of \emph{files}
% shown in the directory tree. If \meta{n} is not given, the list of files will not be saved.
%
% \subsection{Iterating over the shown files}
% \DescribeMacro{\dtForFiles\marg{n}\marg{i}\marg{c}}
% |\dtForFiles| iterates over the list of files saved by |\directoryTree|.
% In the process, it successively defines \meta{i} to each file name from the saved list,
% and executes the code \meta{c}. In \meta{c}, \meta{i} is available as |\i|.
%
% \subsection{Excluding files and directories from the tree}
% \DescribeMacro{\dtSetExclude\marg{regex}}
% Using this macro, you can set a Lua \meta{regex} for file exclusion.
% Paths matching \meta{regex} will not be shown in the directory tree.
% The default exclusion regex just excludes files and folders whose names start with a dot,
% and which are thus hidden on Unix systems.
%
% \subsection{Example}
% |\directoryTree[example]{.}| draws a directory tree with the current working directory at the root
% and saves the list of files for the name \texttt{example}.
% The output of this incantation can be seen in figure~\ref{fig:cwdtree} on page~\pageref{fig:cwdtree}.
%
% \begin{figure}[h]
% \center
% \directoryTree[example]{.}
% \caption{The directory in which this package was compiled}
% \label{fig:cwdtree}
% \end{figure}
%
% \noindent|\dtForFiles{example}{thefile}{(\thefile)}| expands to the following:\\
% {\itshape
% \dtForFiles{example}{thefile}{(\thefile)}
% }\\
% It retrieves the list of files saved with the name \texttt{example} from the tree in figure~\ref{fig:cwdtree},
% defines |\thefile| for each filename and then calls the code given as the last argument,
% which in this example just expands to |(\thefile)|.
%
%
% \StopEventually{}
%
% \subsection{Customizing the output}
% \subsubsection{The TikZ styles}
% This package defines three TikZ styles:
% \begin{itemize}
%	\item \texttt{fsnode} for generic file system nodes
%	\item \texttt{directory} for directories
%	\item \texttt{file} for files
% \end{itemize}
% They can of course be changed to give the file system nodes a custom look and feel.
%
% \subsubsection{Dynamic node text and shape selection}
% To enable custom node text and dynamic shape selection,
% the \lstinline/directoryTree/ table has two overwritable functions,
% \lstinline/label(attr, path)/ and \lstinline/style(attr, path)/.
% The \lstinline/attr/ argument is an attribute table from the Lua file system library,
% and \lstinline/path/ is the path of the file system node.
% See listing~\ref{directory-tree.lua} on page~\pageref{directory-tree.lua} for the default implementation.
%
% Furthermore, there are two overwritable \TeX{} macros for typesetting node and directory labels.
% \DescribeMacro{\dtDirLabel\marg{dirname}} Both of these macros will by default just expand to their first argument.
% \DescribeMacro{\dtFileLabel\marg{filename}} Overwrite these to your liking,
% for example to add a directory symbol to directory labels.
% \section{Implementation}
% First, we load TikZ and its library for trees, and define our node styles.
%    \begin{macrocode}
\RequirePackage{tikz}
\usetikzlibrary{trees}
\tikzstyle{fsnode}=[draw=black,thick,anchor=west]
\tikzstyle{directory}=[fsnode]
\tikzstyle{file}=[fsnode]
%    \end{macrocode}
% Then we define two commands which will be called to typeset the directory and file labels.
% Overwrite these to your liking to change the labels and their formatting.
%    \begin{macrocode}
\newcommand{\dtDirLabel}[1]{#1}
\newcommand{\dtFileLabel}[1]{#1}
%    \end{macrocode}
% We now check if we have Lua\TeX{} before loading the Lua code powering the package.
%    \begin{macrocode}
\RequirePackage{ifluatex}
\ifluatex\else
	\PackageError{directory-tree}{%
		Must be run with LuaTeX/LuaLaTeX!
	}{%
		This package only works with LuaTeX/LuaLaTeX.\MessageBreak
		Thus, you must compile your document with one of the aforementioned programs.
	}
\fi
\directlua{directoryTree = require('directory-tree')}
%    \end{macrocode}
% \begin{macro}{\directoryTree}
%    \begin{macrocode}
\newcommand{\directoryTree}[2][]{
	\begin{tikzpicture}[%
		grow via three points={one child at (0.5,-0.7) and
		two children at (0.5,-0.7) and (0.5,-1.4)},
		edge from parent path={(\tikzparentnode.south) |- (\tikzchildnode.west)}]
		\directlua{directoryTree.createTree('#2','#1');}
	\end{tikzpicture}
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\dtForFiles}
%    \begin{macrocode}
\makeatletter
\newcommand{\dtForFiles}[3]{
	\edef\dt@list{\csname dt@listoffiles@#1\endcsname}
	\expandafter\expandafter\expandafter\@for\csname #2\endcsname:=\dt@list\do{#3}
}
\makeatother
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\dtSetExclude}
%    \begin{macrocode}
\newcommand{\dtSetExclude}[1]{
	\directlua{directoryTree.exclude = #1;}
}
%    \end{macrocode}
% \end{macro}
%
% \subsection{The Lua Filesystem Magic}
% For the Lua code driving this package, see listing~\ref{directory-tree.lua} on page~\pageref{directory-tree.lua}.
% \lstinputlisting[label=directory-tree.lua,caption=directory-tree.lua]{directory-tree.lua}
%
% \clearpage
% \Finale
\endinput