summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/dbshow
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-01-09 03:00:53 +0000
committerNorbert Preining <norbert@preining.info>2022-01-09 03:00:53 +0000
commitfbacb8167ccd172bb0b177974778f228ad41691d (patch)
tree8ad1c76a4dabddbc25abf75b1bc14238e811e9c4 /macros/latex/contrib/dbshow
parentcd2e7ab7ef89a5c3c1935281009729bff0f357e2 (diff)
CTAN sync 202201090300
Diffstat (limited to 'macros/latex/contrib/dbshow')
-rw-r--r--macros/latex/contrib/dbshow/dbshow-doc.pdfbin348241 -> 388176 bytes
-rw-r--r--macros/latex/contrib/dbshow/dbshow-doc.tex444
-rw-r--r--macros/latex/contrib/dbshow/dbshow.sty168
3 files changed, 350 insertions, 262 deletions
diff --git a/macros/latex/contrib/dbshow/dbshow-doc.pdf b/macros/latex/contrib/dbshow/dbshow-doc.pdf
index 3809cbc296..fd03985433 100644
--- a/macros/latex/contrib/dbshow/dbshow-doc.pdf
+++ b/macros/latex/contrib/dbshow/dbshow-doc.pdf
Binary files differ
diff --git a/macros/latex/contrib/dbshow/dbshow-doc.tex b/macros/latex/contrib/dbshow/dbshow-doc.tex
index 02332a1257..40bef33d17 100644
--- a/macros/latex/contrib/dbshow/dbshow-doc.tex
+++ b/macros/latex/contrib/dbshow/dbshow-doc.tex
@@ -11,6 +11,10 @@
\tcbuselibrary{listings, skins, raster, breakable}
\usepackage{tabularray}
+\def\zhdate{2022年1月8日}
+\def\endate{2022/01/08}
+\def\version{v1.2}
+
\IndexPrologue
{
\section*{Index}
@@ -122,21 +126,27 @@
\DeclareDocumentCommand \opt { O{} m }
{ \__codedoc_cmd:no {#1} { #2 } }
+
+\NewDocumentCommand \linktarget { m m m } {%
+ \hyperlink{#1}{#3}%
+ \raisebox{1em}{\hypertarget{#2}{}}%
+}
\ExplSyntaxOff
\begin{document}
\title{
- \pkg{dbshow} 宏包
- \protect\footnote{\url{https://github.com/ZhiyuanLck/dbshow}}
+ \pkg{dbshow} 宏包 \version%
+ \protect\footnote{%
+ 代码仓库:\url{https://github.com/ZhiyuanLck/dbshow},
+ QQ群:788706534}
\rlap{\makebox[4cm][r]{
\normalsize $\Longrightarrow$ \color{red}
- \protect\hyperlink{en}{English Version}
- \protect\hypertarget{zh}{}
+ \linktarget{en}{zh}{English Version}
}}
}
\author{\textit{李昌锴} \texttt{<lichangkai225@qq.com>}}
-\date{2022年1月7日}
+\date{\zhdate}
\maketitle
\tableofcontents
@@ -153,6 +163,8 @@
和其他数据库宏包比如 \pkg{datatool} 相比,\pkg{dbshow} 更专注于非图表类型的数
据展示。
+\subsection{数据类型}
+
宏包基于 \pkg{expl3} 的基础类型构建了6种类型:
\begin{Description}[\texttt{clist}]
\item[\texttt{date}]
@@ -170,8 +182,21 @@
逗号分隔的列表类型。默认值为空列表。
\end{Description}
+\subsection{与 \pkg{datatool} 的区别}
+
+从核心功能上看,\pkg{dbshow} 和 \pkg{datatool} 实现了相同的功能。区别在于
+\pkg{dbshow} 基于 \pkg{expl3} 实现,支持字符串的正则匹配,还支持多级排序。使用
+方式上更倾向于样式与内容分离,所有的样式都可以通过选项提前定义好并且可以复用。
+\pkg{dbshow} 并没有实现从外部文件读取数据以及将数据持久化的功能,我认为这些应
+该是更专业的外部程序的工作而不应该在 \LaTeX 中设计这些功能。因此,\pkg{dbshow}
+只提供了一个运行时的临时数据库,足够轻便且满足大部分正常需求。如果你想删除或修
+改数据库中某一条记录,请去对应的位置删除或修改掉对应的 \env{dbitem} 环境,而不
+是让宏包提供一个输出某一行记录的命令。某种意义上记录数据库的 \TeX 源文件本身就
+是数据的一种持久化。
+
\section{接口文档}
-\subsection{\cs{dbNewDatabase}}
+
+\subsection{创建、展示和清空数据库}
\begin{function}{\dbNewDatabase, \dbNewDatabase*}
\begin{syntax}
\cs{dbNewDatabase} \oarg{base database} \marg{database} \{ \\
@@ -222,6 +247,23 @@
}
\end{verbatim}
+\begin{function}{\dbshow}
+ \begin{syntax}
+ \cs{dbshow} \marg{style} \marg{database}
+ \end{syntax}
+
+ 使用 \meta{style} 样式来展示 \meta{database}。
+\end{function}
+
+\begin{function}{\dbclear}
+ \begin{syntax}
+ \cs{dbclear} \marg{database}
+ \end{syntax}
+
+ 清空 \meta{database} 里的所有内容。
+
+\end{function}
+
\subsection{\cs{dbNewStyle} 和样式选项}
\begin{function}{\dbNewStyle}
@@ -233,7 +275,7 @@
\meta{base styles},比如 |\dbNewStyle[base1, base2]{new-style}{ques}{}|。
\end{function}
-\bigskip
+\subsubsection{通用选项}
\begin{option}{opt=filter, desc={= \meta{filter}}, init=-none-}
为当前样式设置由 \cs{dbCombineFilters} 所定义的过滤器
@@ -282,6 +324,68 @@
\end{verbatim}
\begin{option}{
+ opt = item-code,
+ desc = {= \meta{item code}}
+}
+ 该选项用来设置展示数据库中每条记录的代码。你可以使用 \cs{dbuse} 来展示属性的
+ 值。
+\end{option}
+
+\begin{option}{
+ opt = {\meta{attr}/sep},
+ desc = {= \meta{sep spec}},
+ init = {,~\~}
+}
+\begin{Syntax}
+ \meta{attr}/sep = \meta{separator} \\
+ \meta{attr}/sep = \{ \\
+ ~~\meta{separator between two}, \\
+ ~~\meta{separator between more than two}, \\
+ ~~\meta{separator between final two} \\
+ \}
+\end{Syntax}
+
+ 该选项只适用于类型为 |clist| 的属性,用来设置列表间元素的间隔。第一个版本接
+ 受一个参数,将所有的元素间隔设置为 \meta{separator}。第二个版本接受逗号分隔
+ 的三个参数,分别用来设置只有两个元素时的分隔符 \meta{separator between two},
+ 超过两个元素时的分隔符 \meta{separator between more than two},和最后两个元
+ 素之间的分隔符 \meta{separator between final two}。
+
+\end{option}
+
+\subsubsection{装饰器}
+
+下面这些选项在不同层次上装饰原有的展示代码,有些其实不必通过选项的形式来装饰,
+但这样做的好处是可以进一步使样式与内容分离。下面的例子中,\meta{style1} 和
+\meta{style2} 是相同的样式,都用 * 将 \meta{attr1} 包裹住了,但是如果你还想定
+义一个样式用 = 将 \meta{attr1} 包裹住,如果用 \meta{style1} 的方式,那就可能
+需要重复大片代码,用 \meta{style2} 的方式则可以很轻松的继承 \meta{style1} 中的
+代码。
+
+\begin{verbatim}
+ \dbNewStyle{style1}{db}{
+ item-code = {%
+ *\rvuse{attr1}*\rvuse{attr2}
+ % more code
+ }
+ }
+ \dbNewStyle{base-style}{db}{
+ item-code = {%
+ \rvuse{attr1}\rvuse{attr2}
+ % more code
+ }
+ }
+ \dbNewStyle[base-style]{style2}{db}{
+ attr1/before-code = { * },
+ attr1/after-code = { * },
+ }
+ \dbNewStyle[base-style]{style3}{db}{
+ attr1/before-code = { = },
+ attr1/after-code = { = },
+ }
+\end{verbatim}
+
+\begin{option}{
opt = before-code,
desc = {= \meta{before code}}
}
@@ -296,11 +400,17 @@
\end{option}
\begin{option}{
- opt = item-code,
- desc = {= \meta{item code}}
+ opt = record-before-code,
+ desc = {= \meta{before code}}
}
- 该选项用来设置展示数据库中每条记录的代码。你可以使用 \cs{dbuse} 来展示属性的
- 值。
+ 该选项用来设置在展示当前记录之前需要执行的代码。
+\end{option}
+
+\begin{option}{
+ opt = record-after-code,
+ desc = {= \meta{after code}}
+}
+ 该选项用来设置在展示当前记录之后需要执行的代码。
\end{option}
\begin{option}{
@@ -320,29 +430,7 @@
\end{option}
\begin{option}{
- opt = {\meta{attr}/sep},
- desc = {= \meta{sep spec}},
- init = {,~\~}
-}
-\begin{Syntax}
- \meta{attr}/sep = \meta{separator} \\
- \meta{attr}/sep = \{ \\
- ~~\meta{separator between two}, \\
- ~~\meta{separator between more than two}, \\
- ~~\meta{separator between final two} \\
- \}
-\end{Syntax}
-
- 该选项只适用于类型为 |clist| 的属性,用来设置列表间元素的间隔。第一个版本接
- 受一个参数,将所有的元素间隔设置为 \meta{separator}。第二个版本接受逗号分隔
- 的三个参数,分别用来设置只有两个元素时的分隔符 \meta{separator between two},
- 超过两个元素时的分隔符 \meta{separator between more than two},和最后两个元
- 素之间的分隔符 \meta{separator between final two}。
-
-\end{option}
-
-\begin{option}{
- opt = item-before-code,
+ opt = {\meta{attr}/item-before-code},
desc = {= \meta{before code}}
}
该选项只适用于类型为 |clist| 的属性,用来设置展示列表每个元素前需要执行的代
@@ -350,7 +438,7 @@
\end{option}
\begin{option}{
- opt = item-after-code,
+ opt = {\meta{attr}/item-after-code},
desc = {= \meta{after code}}
}
该选项只适用于类型为 |clist| 的属性,用来设置展示列表每个元素后需要执行的代
@@ -474,29 +562,26 @@
\subsection{\cs{dbsave} 和 \cs{dbuse}}
-\begin{function}{\dbsave, \dbuse}
+\begin{function}{\dbsave}
\begin{syntax}
- \cs{dbsave} \marg{attr} \marg{data} \\
- \cs{dbuse} \marg{attr} \\
+ \cs{dbsave} \marg{attr} \marg{data}
\end{syntax}
- \cs{dbsave} 用来存储数据,只能在 \env{item} 环境中使用。\cs{dbuse} 用来使用
- 数据,只能在 \opt{item-code} 选项中使用。
+ \cs{dbsave} 用来存储数据,只能在 \env{item} 环境中使用。
\end{function}
-\subsection{使用 \cs{dbshow} 展示数据库}
-
-\begin{function}{\dbshow}
+\begin{function}[EXP]{\dbuse}
\begin{syntax}
- \cs{dbshow} \marg{style} \marg{database}
+ \cs{dbuse} \marg{attr}
\end{syntax}
- 使用 \meta{style} 样式来展示 \meta{database}。
+ \cs{dbuse} 用来使用数据,只能在 \opt{item-code} 选项中使用。\cs{dbuse} 是可
+ 展开的。
\end{function}
\subsection{条件判别式}
-\begin{function}{\dbIfEmptyT, \dbIfEmptyF, \dbIfEmptyTF}
+\begin{function}[EXP]{\dbIfEmptyT, \dbIfEmptyF, \dbIfEmptyTF}
\begin{syntax}
\cs{dbIfEmptyTF} \marg{true code} \marg{false code} \\
\cs{dbIfEmptyT} \marg{true code} \\
@@ -514,44 +599,6 @@
}
\end{verbatim}
-\begin{function}{\dbItemIfEmptyT, \dbItemIfEmptyF, \dbItemIfEmptyTF}
- \begin{syntax}
- \cs{dbItemIfEmptyTF} \marg{true code} \marg{false code} \\
- \cs{dbItemIfEmptyT} \marg{true code} \\
- \cs{dbItemIfEmptyF} \marg{false code}
- \end{syntax}
-
- 该判别式用来判断当前元素是否为空。下面的示例展示了如何在展示 |database-test|
- 数据库中 |text| 属性的元素时在元素非空的时候前后都加上 |*|。
-\end{function}
-
-\begin{verbatim}
- \dbNewStyle{style-cond2}{database-test}{
- text/before-code = {\dbItemIfEmptyF{*}},
- text/after-code = {\dbItemIfEmptyF{*}},
- }
-\end{verbatim}
-
-\begin{function}{\dbClistItemIfEmptyT, \dbClistItemIfEmptyF, \dbClistItemIfEmptyTF}
- \begin{syntax}
- \cs{dbClistItemIfEmptyTF} \marg{true code} \marg{false code} \\
- \cs{dbClistItemIfEmptyT} \marg{true code} \\
- \cs{dbClistItemIfEmptyF} \marg{false code}
- \end{syntax}
-
- 该判别式用来判断列表属性中的元素是否为空。下面的示例展示了如何在展示
- |database-test| 数据库中 |labels| 属性(标签列表)的元素时在标签非空的时候前
- 后都加上 |*|。
-\end{function}
-
-\begin{verbatim}
- \dbNewDatabase{database-test}{labels=clist}
- \dbNewStyle{style-cond3}{database-test}{
- labels/item-before-code = {\dbClistItemIfEmptyF{*}},
- labels/item-after-code = {\dbClistItemIfEmptyF{*}},
- }
-\end{verbatim}
-
\subsection{特殊命令}
\pkg{dbshow} 定义了一些特殊的命令,会根据语境展开为不同的内容。
@@ -580,16 +627,17 @@
见第 \ref{sec:example} 节。
\title{
- Package \pkg{dbshow}
- \protect\footnote{\url{https://github.com/ZhiyuanLck/dbshow}}
+ Package \pkg{dbshow} \version%
+ \protect\footnote{%
+ Repository: \url{https://github.com/ZhiyuanLck/dbshow},
+ Telegram Group: \url{https://t.me/latex_dbshow}}
\rlap{\makebox[4cm][r]{
\normalsize $\Longrightarrow$ \color{red}
- \protect\hyperlink{zh}{中文版本}
- \protect\hypertarget{en}{}
+ \linktarget{zh}{en}{中文版本}
}}
}
\author{Li Changkai \texttt{<lichangkai225@qq.com>}}
-\date{2022/01/07}
+\date{\endate}
\maketitle
\section{Introduction}
@@ -605,6 +653,8 @@ The package provides four core functions: data storage and display, data
filtering, data sorting and data display. All data is saved once and then you
can display these data with custom filters, orders and styles.
+\subsection{Data Types}
+
The package constructs 6 types based on the internal typed of \pkg{expl3}:
\begin{Description}[\texttt{clist}]
\item[\texttt{date}]
@@ -622,9 +672,25 @@ The package constructs 6 types based on the internal typed of \pkg{expl3}:
comma list, default empty.
\end{Description}
+\subsection{Comparison to \pkg{datatool}}
+
+\pkg{dbshow} and \pkg{datatool} implement the same core functions. But
+\pkg{dbshow} is based on \pkg{expl3} and it supports string regex and
+multi-level sorting. \pkg{dbshow} tries to divide style from the contents
+(data in database): all styles are predefined and can be reused conveniently
+so that there can be only codes to save data and one-line code to show the
+database inside the \env{document} environment. You can hide the details in
+the preamble and focus on the data you want to display. \pkg{dbshow} provides
+a simple temporary runtime database, which means it can not input and output
+data from/to extern files (they should be responsible by some professional
+programming languages). When you need to delete or revise a record, just go to
+where it is recorded in the source code rather than use a macro to manipulate
+data after they are saved. In a sense, \TeX~file is also a kind of data
+persistence.
+
\section{Interfaces}
-\subsection{\cs{dbNewDatabase}}
+\subsection{Create, Display and Clear Database}
\begin{function}{\dbNewDatabase, \dbNewDatabase*}
\begin{syntax}
@@ -670,6 +736,23 @@ The example below define a database named |ques|.
}
\end{verbatim}
+\begin{function}{\dbshow}
+ \begin{syntax}
+ \cs{dbshow} \marg{style} \marg{database}
+ \end{syntax}
+
+ Show the \meta{database} with \meta{style}.
+\end{function}
+
+\begin{function}{\dbclear}
+ \begin{syntax}
+ \cs{dbclear} \marg{database}
+ \end{syntax}
+
+ Clear the content of \meta{database}.
+
+\end{function}
+
\subsection{\cs{dbNewStyle} and Style Options}
\begin{function}{\dbNewStyle}
@@ -682,7 +765,7 @@ from a list of \meta{base styles} such as
|\dbNewStyle[base1, base2]{new-style}{ques}{}|.
\end{function}
-\bigskip
+\subsubsection{General Options}
\begin{option}{opt=filter, desc={= \meta{filter}}, init=-none-}
Set the \meta{filter} defined by \cs{dbCombineFilters}.
@@ -734,20 +817,6 @@ from a list of \meta{base styles} such as
\end{verbatim}
\begin{option}{
- opt = before-code,
- desc = {= \meta{before code}}
-}
- Set the \meta{before code} that is executed before displaying the database.
-\end{option}
-
-\begin{option}{
- opt = after-code,
- desc = {= \meta{after code}}
-}
- Set the \meta{after code} that is executed after displaying the database.
-\end{option}
-
-\begin{option}{
opt = item-code,
desc = {= \meta{item code}}
}
@@ -756,22 +825,6 @@ from a list of \meta{base styles} such as
\end{option}
\begin{option}{
- opt = {\meta{attr}/before-code},
- desc = {= \meta{before code}}
-}
- Set the \meta{before code} that is executed by \cs{dbuse} before displaying
- certain attribute.
-\end{option}
-
-\begin{option}{
- opt = {\meta{attr}/after-code},
- desc = {= \meta{after code}}
-}
- Set the \meta{after code} that is executed by \cs{dbuse} after displaying
- certain attribute.
-\end{option}
-
-\begin{option}{
opt = {\meta{attr}/sep},
desc = {= \meta{sep spec}},
init = {,~\~}
@@ -801,8 +854,87 @@ from a list of \meta{base styles} such as
\end{option}
+\subsubsection{Decorators}
+
+The options below serves as decorators. In some cases, decorator can also be
+encoded directly into |item-code| or some other places, which is convenient
+sometimes. The benefit of defining decorators with options is that styles step
+further to be divided with contents. In the examples below, \meta{style1} and
+\meta{style2} is the same style, which wrap \meta{attr1} with *. When you want
+another style which wrap \meta{attr1} with =, if you choose the way of
+\meta{style1}, \meta{item code} are repeated, otherwise if you choose the way
+of \meta{style2}, \meta{item code} is inherited and you only need define the
+decorators.
+
+\begin{verbatim}
+ \dbNewStyle{style1}{db}{
+ item-code = {%
+ *\rvuse{attr1}*\rvuse{attr2}
+ % more code
+ }
+ }
+ \dbNewStyle{base-style}{db}{
+ item-code = {%
+ \rvuse{attr1}\rvuse{attr2}
+ % more code
+ }
+ }
+ \dbNewStyle[base-style]{style2}{db}{
+ attr1/before-code = { * },
+ attr1/after-code = { * },
+ }
+ \dbNewStyle[base-style]{style3}{db}{
+ attr1/before-code = { = },
+ attr1/after-code = { = },
+ }
+\end{verbatim}
+
\begin{option}{
- opt = item-before-code,
+ opt = before-code,
+ desc = {= \meta{before code}}
+}
+ Set the \meta{before code} that is executed before displaying the database.
+\end{option}
+
+\begin{option}{
+ opt = after-code,
+ desc = {= \meta{after code}}
+}
+ Set the \meta{after code} that is executed after displaying the database.
+\end{option}
+
+\begin{option}{
+ opt = record-before-code,
+ desc = {= \meta{before code}}
+}
+ Set the \meta{before code} that is executed before displaying the record.
+\end{option}
+
+\begin{option}{
+ opt = record-after-code,
+ desc = {= \meta{after code}}
+}
+ Set the \meta{after code} that is executed after displaying the record.
+\end{option}
+
+\begin{option}{
+ opt = {\meta{attr}/before-code},
+ desc = {= \meta{before code}}
+}
+ Set the \meta{before code} that is executed by \cs{dbuse} before displaying
+ certain attribute.
+\end{option}
+
+\begin{option}{
+ opt = {\meta{attr}/after-code},
+ desc = {= \meta{after code}}
+}
+ Set the \meta{after code} that is executed by \cs{dbuse} after displaying
+ certain attribute.
+\end{option}
+
+\begin{option}{
+ opt = {\meta{attr}/item-before-code},
desc = {= \meta{before code}}
}
Only for attributes of type |clist|. Set the \meta{after code} that is
@@ -810,7 +942,7 @@ from a list of \meta{base styles} such as
\end{option}
\begin{option}{
- opt = item-after-code,
+ opt = {\meta{attr}/item-after-code},
desc = {= \meta{after code}}
}
Only for attributes of type |clist|. Set the \meta{after code} that is
@@ -939,30 +1071,27 @@ code is showned below.
\subsection{\cs{dbsave} and \cs{dbuse}}
-\begin{function}{\dbsave, \dbuse}
+\begin{function}{\dbsave}
\begin{syntax}
- \cs{dbsave} \marg{attr} \marg{data} \\
- \cs{dbuse} \marg{attr} \\
+ \cs{dbsave} \marg{attr} \marg{data}
\end{syntax}
- Date is stored with \cs{dbsave} and is displayed with \cs{dbuse}. \cs{dbsave}
- can be used only inside the \env{dbitem} environment and \cs{dbuse} can be
- only used inside the option \opt{item-code}.
+ \cs{dbsave} save the \meta{data} to \meta{attr} of current record.
+ \cs{dbsave} can be used only inside the \env{dbitem} environment.
\end{function}
-\subsection{Use \cs{dbshow} to Display the Database}
-
-\begin{function}{\dbshow}
+\begin{function}[EXP]{\dbuse}
\begin{syntax}
- \cs{dbshow} \marg{style} \marg{database}
+ \cs{dbuse} \marg{attr}
\end{syntax}
- Show the \meta{database} with \meta{style}.
+ Display the value of \meta{attr} of current record. \cs{dbuse} is
+ \textbf{expandable} and can be only used inside the option \opt{item-code}.
\end{function}
\subsection{Conditionals}
-\begin{function}{\dbIfEmptyT, \dbIfEmptyF, \dbIfEmptyTF}
+\begin{function}[EXP]{\dbIfEmptyT, \dbIfEmptyF, \dbIfEmptyTF}
\begin{syntax}
\cs{dbIfEmptyTF} \marg{true code} \marg{false code} \\
\cs{dbIfEmptyT} \marg{true code} \\
@@ -981,43 +1110,6 @@ code is showned below.
}
\end{verbatim}
-\begin{function}{\dbItemIfEmptyT, \dbItemIfEmptyF, \dbItemIfEmptyTF}
- \begin{syntax}
- \cs{dbItemIfEmptyTF} \marg{true code} \marg{false code} \\
- \cs{dbItemIfEmptyT} \marg{true code} \\
- \cs{dbItemIfEmptyF} \marg{false code}
- \end{syntax}
-
- Test if the value of the attribute is empty. The example belows shows how to
- surround the non-empty |text| attribute with the symbol *.
-\end{function}
-
-\begin{verbatim}
- \dbNewStyle{style-cond2}{database-test}{
- text/before-code = {\dbItemIfEmptyF{*}},
- text/after-code = {\dbItemIfEmptyF{*}},
- }
-\end{verbatim}
-
-\begin{function}{\dbClistItemIfEmptyT, \dbClistItemIfEmptyF, \dbClistItemIfEmptyTF}
- \begin{syntax}
- \cs{dbClistItemIfEmptyTF} \marg{true code} \marg{false code} \\
- \cs{dbClistItemIfEmptyT} \marg{true code} \\
- \cs{dbClistItemIfEmptyF} \marg{false code}
- \end{syntax}
-
- Test if the item of comma list is empty. The example belows shows how to
- surround the non-empty label with the symbol *.
-\end{function}
-
-\begin{verbatim}
- \dbNewDatabase{database-test}{labels=clist}
- \dbNewStyle{style-cond3}{database-test}{
- labels/item-before-code = {\dbClistItemIfEmptyF{*}},
- labels/item-after-code = {\dbClistItemIfEmptyF{*}},
- }
-\end{verbatim}
-
\subsection{Special Macros}
Some special macros are defined to expand to different contents according to context.
@@ -1251,6 +1343,14 @@ run pdflatex
Add style option: \opt{raw-filter}
} \\
2022-01-07 & 1.1 & Improve example \\
+ 2022-01-07 & 1.1.1 & Add macro: \cmd{\dbclear} \\
+ 2022-01-07 & 1.1.2 & Add documentation: comparison to \pkg{datatool} \\
+ 2022-01-08 & 1.2 & {
+ Fix str sorting bug \\
+ Remove macros: \cmd{\dbItemIfEmpty(TF)}, \cmd{\dbClistItemIfEmpty(TF)} \\
+ Make \cs{dbuse} expandable \\
+ Add option: \opt{record-before-code}, \opt{record-after-code}
+ } \\
\end{tblr}
\end{documentation}
diff --git a/macros/latex/contrib/dbshow/dbshow.sty b/macros/latex/contrib/dbshow/dbshow.sty
index 0b02c20311..68ac7b1d35 100644
--- a/macros/latex/contrib/dbshow/dbshow.sty
+++ b/macros/latex/contrib/dbshow/dbshow.sty
@@ -14,8 +14,8 @@
% The Current Maintainer of this work is Li Changkai.
%
% This work consists of the files dbshow.sty, dbshow-doc.tex.
-\def\myfileversion{1.1}
-\def\myfiledate{2022/01/07}
+\def\myfileversion{v1.2}
+\def\myfiledate{2022/01/08}
\RequirePackage{expl3, xparse}
\RequirePackage[calc]{datetime2}
\ProvidesExplPackage
@@ -97,16 +97,16 @@
sep~=~\{#2\}~\msg_line_context:.
}
-\msg_new:nnn { dbshow } { unsupported-sort-type } {
- unsupported~sort~type:~'#1'~\msg_line_context:.~The~type~should~be~one~of~
- \{str,~date,~int,~fp\}.
-}
-
\cs_new:Nn \dbshow_sep_error:nn {
\msg_error:nnnn { dbshow } { wrong-seperator } { #1 } { #2 }
}
\cs_generate_variant:Nn \dbshow_sep_error:nn { xx }
+\msg_new:nnn { dbshow } { unsupported-sort-type } {
+ unsupported~sort~type:~'#1'~\msg_line_context:.~The~type~should~be~one~of~
+ \{str,~date,~int,~fp\}.
+}
+
\clist_const:Nn \dbshow_type_clist { date, str, tl, clist, int, fp }
\prop_const_from_keyval:Nn \dbshow_new_cs_map {
@@ -127,15 +127,6 @@
fp = fp_gset:cn
}
-\prop_const_from_keyval:Nn \dbshow_use_cs_map {
- date = str_use:c,
- str = str_use:c,
- tl = tl_use:c,
- clist = dbshow_clist_use:c,
- int = int_use:c,
- fp = fp_use:c
-}
-
\prop_const_from_keyval:Nn \dbshow_default_value {
date = \Today,
str = ,
@@ -146,6 +137,14 @@
}
\newcount\l_dbshow_date_diff
+\clist_new:N \l_style_sep_clist
+\tl_new:N \l_style_item_before_code
+\tl_new:N \l_style_item_after_code
+\cs_generate_variant:Nn \clist_use:nn { xx }
+\cs_generate_variant:Nn \clist_use:nnnn { xxxx }
+\prg_generate_conditional_variant:Nnn \str_compare:nNn { VNV } { TF }
+\prg_generate_conditional_variant:Nnn \int_compare:nNn { VNV } { TF }
+\prg_generate_conditional_variant:Nnn \fp_compare:nNn { VNV } { TF }
% #1 database #2 attr #3 type #4 default value
\cs_new:Npn \dbshow_process_default_value:w #1|#2=#3|#4\scan_stop {
@@ -208,6 +207,10 @@
\int_gincr:c { g__dbshow_counter_#1 }
}
+\NewDocumentCommand { \dbclear } { m } {
+ \int_gzero:c { g__dbshow_counter_#1 }
+}
+
% #1 database #2 attr #3 content
\cs_new:Nn \dbshow_save_data:nnn {
\dbshow_check_attr:nn { #1 } { #2 }
@@ -221,53 +224,53 @@
}
\cs_generate_variant:Nn \dbshow_save_data:nnn { nnx }
-\cs_new:Nn \dbshow_clist_use:N {
- \clist_clear:N \l_tmpa_clist
-
- \clist_map_inline:Nn #1 {
- \prg_set_conditional:Nnn \dbshow_clist_item_if_empty: { T, F, TF } {
- \tl_if_empty:nTF { ##1 }
- { \prg_return_true: }
- { \prg_return_false: }
- }
- \cs_set_eq:NN \dbClistItemIfEmptyT\dbshow_clist_item_if_empty:T
- \cs_set_eq:NN \dbClistItemIfEmptyF\dbshow_clist_item_if_empty:F
- \cs_set_eq:NN \dbClistItemIfEmptyTF\dbshow_clist_item_if_empty:TF
-
- \clist_put_right:Nn \l_tmpa_clist {
- \l_style_item_before_code
- ##1
- \l_style_item_after_code
- }
- }
+\cs_new:Nn \dbshow_brace:n {
+ \exp_not:n { { #1 } }
+}
- \tl_clear:N \l_tmpa_tl
- \clist_map_inline:Nn \l_style_sep_clist {
- \tl_put_right:Nn \l_tmpa_tl { { ##1 } }
- }
+% #1 before code tl #2 after code tl #3 item
+\cs_new:Nn \dbshow_clist_wrapper:NNn {
+ \exp_not:n { { #1#3#2 }, }
+}
- \int_set:Nn \l_tmpa_int { \clist_count:N \l_style_sep_clist }
- \int_case:nnF { \l_tmpa_int } {
+% #1 clist #2 sep #3 before code tl #4 after code tl
+\cs_new:Nn \dbshow_clist_use:NNNN {
+ \int_case:nnF { \clist_count:N #2 } {
{ 1 } {
- \exp_after:wN \clist_use:Nn \exp_after:wN \l_tmpa_clist \l_tmpa_tl
+ \clist_use:xx
+ { \clist_map_tokens:Nn #1 { \dbshow_clist_wrapper:NNn #3 #4 } }
+ { \clist_item:Nn #2 { 1 } }
}
{ 3 } {
- \exp_after:wN \clist_use:Nnnn \exp_after:wN \l_tmpa_clist \l_tmpa_tl
+ \clist_use:xxxx
+ { \clist_map_tokens:Nn #1 { \dbshow_clist_wrapper:NNn #3 #4 } }
+ { \clist_item:Nn #2 { 1 } }
+ { \clist_item:Nn #2 { 2 } }
+ { \clist_item:Nn #2 { 3 } }
}
- }
- {
+ } {
\dbshow_sep_error:xx
- { \int_use:N \l_tmpa_int }
- { \clist_use:Nn \l_style_sep_clist { , } }
+ { \clist_count:N #2 }
+ { \clist_use:Nn #2 { , } }
}
}
-\cs_generate_variant:Nn \dbshow_clist_use:N { c }
-
-% #1 database #2 attr #3 index
-\cs_new:Nn \dbshow_use_data:nnn {
- \str_set:Nx \l_tmp_type { \dbshow_get_type:nn { #1 } { #2 } }
- \prop_get:NVN \dbshow_use_cs_map \l_tmp_type \l_tmp_cs
- \use:c { \l_tmp_cs } { g__dbshow_data_#1_#2_#3 }
+\cs_generate_variant:Nn \dbshow_clist_use:NNNN { cccc }
+
+% #1 database #2 attr #3 index #4 style
+\cs_new:Nn \dbshow_use_data:nnnn {
+ \str_case_e:nn { \prop_item:cn { g__dbshow_type_map_#1 } { #2 } } {
+ { date } { \str_use:c { g__dbshow_data_#1_#2_#3 } }
+ { str } { \str_use:c { g__dbshow_data_#1_#2_#3 } }
+ { tl } { \tl_use:c { g__dbshow_data_#1_#2_#3 } }
+ { int } { \int_use:c { g__dbshow_data_#1_#2_#3 } }
+ { fp } { \fp_use:c { g__dbshow_data_#1_#2_#3 } }
+ { clist } {
+ \dbshow_clist_use:cccc { g__dbshow_data_#1_#2_#3 }
+ { g__dbshow_style_clist_sep_#4_#1_#2 }
+ { g__dbshow_style_clist_item_before_#4_#1_#2 }
+ { g__dbshow_style_clist_item_after_#4_#1_#2 }
+ }
+ }
}
% #1 database
@@ -469,19 +472,19 @@
\cs_new_protected:Nn \dbshow_new_attr_style:nnn {
\dbshow_check_attr:nn { #2 } { #3 }
\keys_define:nn { dbshow/style/#1/#3 } {
- before-code .tl_gset:c = { g__dbshow_style_before_#1_#2_#3 },
+ before-code .tl_gset:c = { g__dbshow_style_attr_before_#1_#2_#3 },
before-code .initial:n = ,
- after-code .tl_gset:c = { g__dbshow_style_after_#1_#2_#3 },
+ after-code .tl_gset:c = { g__dbshow_style_attr_after_#1_#2_#3 },
after-code .initial:n = ,
}
\prop_get:cnN { g__dbshow_type_map_#2 } { #3 } \l_tmp_type
\str_if_eq:eeT { \l_tmp_type } { clist } {
\keys_define:nn { dbshow/style/#1/#3 } {
- sep .clist_gset:c = { g__dbshow_style_sep_#1_#2_#3 },
+ sep .clist_gset:c = { g__dbshow_style_clist_sep_#1_#2_#3 },
sep .initial:n = { { ,~ } },
- item-before-code .tl_gset:c = { g__dbshow_style_item_before_#1_#2_#3 },
+ item-before-code .tl_gset:c = { g__dbshow_style_clist_item_before_#1_#2_#3 },
item-before-code .initial:n = ,
- item-after-code .tl_gset:c = { g__dbshow_style_item_after_#1_#2_#3 },
+ item-after-code .tl_gset:c = { g__dbshow_style_clist_item_after_#1_#2_#3 },
item-after-code .initial:n = ,
}
}
@@ -507,6 +510,10 @@
item-code .initial:n = ,
after-code .tl_gset:c = { g__dbshow_style_after_#1_#2 },
after-code .initial:n = ,
+ record-before-code .tl_gset:c = { g__dbshow_style_record_before_#1_#2 },
+ record-before-code .initial:n = ,
+ record-after-code .tl_gset:c = { g__dbshow_style_record_after_#1_#2 },
+ record-after-code .initial:n = ,
}
\prop_map_inline:cn { g__dbshow_type_map_#2 } {
\dbshow_new_attr_style:nnn { #1 } { #2 } { ##1 }
@@ -566,13 +573,11 @@
}
\str_if_eq:eeT { \l_tmp_type } { date }
{ \str_set:Nn \l_tmp_type { str } }
- \cs_set_eq:Nc \dbshow_compare { \l_tmp_type _compare:nNnTF }
+ \cs_set_eq:Nc \dbshow_compare { \l_tmp_type _compare:VNVTF }
- \exp_args:NnV
- \dbshow_compare { \l_tmpa_tl } \l_op_same { \l_tmpb_tl }
+ \dbshow_compare \l_tmpa_tl \l_op_same \l_tmpb_tl
{ \sort_return_same: }
{
- \exp_args:NnV
\dbshow_compare { \l_tmpa_tl } \l_op_swap { \l_tmpb_tl }
{ \sort_return_swapped: }
{
@@ -621,34 +626,15 @@
\tl_set:Nn \dbIndex { ##1 }
% ####1 attr
- \cs_set:Npn \dbuse ####1 {
+ \DeclareExpandableDocumentCommand { \dbuse } { m } {
\dbshow_check_attr:nn { #2 } { ####1 }
- \clist_set_eq:Nc \l_style_sep_clist
- { g__dbshow_style_sep_#1_#2_####1 }
- \tl_set_eq:Nc \l_style_item_before_code
- { g__dbshow_style_item_before_#1_#2_####1 }
- \tl_set_eq:Nc \l_style_item_after_code
- { g__dbshow_style_item_after_#1_#2_####1 }
-
- \prop_get:cnN { g__dbshow_type_map_#2 } { ####1 } \l_tmp_type
- % \tl_show:N \l_tmp_type
- \str_if_eq:eeT { \l_tmp_type } { date }
- { \tl_set:Nn \l_tmp_type { str } }
- \prg_set_conditional:Nnn \dbshow_item_if_empty: { T, F, TF } {
- \use:c { \l_tmp_type _if_empty:cTF }
- { g__dbshow_data_#2_####1_##1 }
- { \prg_return_true: }
- { \prg_return_false: }
- }
- \cs_set_eq:NN \dbItemIfEmptyT\dbshow_item_if_empty:T
- \cs_set_eq:NN \dbItemIfEmptyF\dbshow_item_if_empty:F
- \cs_set_eq:NN \dbItemIfEmptyTF\dbshow_item_if_empty:TF
-
- \tl_use:c { g__dbshow_style_before_#1_#2_####1 }
- \dbshow_use_data:nnn { #2 } { ####1 } { ##1 }
- \tl_use:c { g__dbshow_style_after_#1_#2_####1 }
+ \tl_use:c { g__dbshow_style_attr_before_#1_#2_####1 }
+ \dbshow_use_data:nnnn { #2 } { ####1 } { ##1 } { #1 }
+ \tl_use:c { g__dbshow_style_attr_after_#1_#2_####1 }
}
+ \tl_use:c { g__dbshow_style_record_before_#1_#2 }
\tl_use:c { g__dbshow_style_database_item_#1_#2 }
+ \tl_use:c { g__dbshow_style_record_after_#1_#2 }
}
\prg_set_conditional:Nnn \dbshow_if_empty: { T, F, TF } {
\clist_if_empty:NTF \l_index
@@ -668,8 +654,10 @@
\NewDocumentCommand { \dbshow } { m m } {
\dbshow_check_database:n { #2 }
\tl_set_eq:Nc \l_dbshow_filter { g__dbshow_filter_#1_#2 }
- \dbshow_check_filter:nn { #2 } { \l_dbshow_filter }
- \dbshow_init_iterator:nnn { #1 } { #2 } { \l_dbshow_filter }
+ \exp_args:Nnv \dbshow_check_filter:nn
+ { #2 } { g__dbshow_filter_#1_#2 }
+ \exp_args:Nnnv \dbshow_init_iterator:nnn
+ { #1 } { #2 } { g__dbshow_filter_#1_#2 }
}
\endinput