diff options
Diffstat (limited to 'macros/latex/contrib/dbshow/dbshow-doc.tex')
-rw-r--r-- | macros/latex/contrib/dbshow/dbshow-doc.tex | 1662 |
1 files changed, 0 insertions, 1662 deletions
diff --git a/macros/latex/contrib/dbshow/dbshow-doc.tex b/macros/latex/contrib/dbshow/dbshow-doc.tex deleted file mode 100644 index ebfe69c535..0000000000 --- a/macros/latex/contrib/dbshow/dbshow-doc.tex +++ /dev/null @@ -1,1662 +0,0 @@ -\documentclass[full]{l3doc} -\usepackage[scheme=plain, fontset=ubuntu]{ctex} -\usepackage{multicol} -\usepackage{adjustbox} -\usepackage{zhlineskip} -\usepackage{enumitem} -\usepackage{indentfirst} -\usepackage{titling} -\usepackage{geometry} -\usepackage{tabularray} -\usepackage{xcolor} -\usepackage{tcolorbox} -\tcbuselibrary{listings, skins, raster, breakable} -\usepackage{tabularray} - -\def\zhdate{2022年1月10日} -\def\endate{2022/01/10} -\def\version{v1.3} - -\geometry{ - left=4.5cm, - right=2cm, - top=2cm, - bottom=2cm, -} -\hypersetup { - CJKbookmarks, - bookmarksopen, - bookmarksopenlevel=3, - pdfstartview=FitH, - pdfinfo = { - Title = The package 'dbshow' , - Subject = A LaTeX package , - Author = Li Changkai - } -} - -\IndexPrologue { - \part*{Index} - \markboth{Index}{Index} - \addcontentsline{toc}{part}{Index} - The~italic~numbers~denote~the~pages~where~the~ - corresponding~entry~is~described,~ - numbers~underlined~point~to~the~definition,~ - all~others~indicate~the~places~where~it~is~used. -} - -\GlossaryPrologue { - \part*{Change~History} - {\GlossaryParms\ttfamily\hyphenchar\font=`\-} - \markboth{Change~History}{Change~History} - \addcontentsline{toc}{part}{Change~History} -} - -\let\subsubitem\subitem - -\DoNotIndex{\begin, \end} -\setlength{\parskip}{\medskipamount} - -\newcommand\tikzmark[1]{\tikz \coordinate[overlay, remember picture] (#1);} -\def\levelchar{?} -\def\orbar{\textup{\textbar}} -\def\defaultval#1{\textbf{\textup{#1}}} -\def\TF{true\orbar false} -\def\TTF{\defaultval{true}\orbar false} -\def\TFF{true\orbar\defaultval{false}} -\def\zhbefore{\textbf{前}} -\def\zhafter{\textbf{后}} -\def\enbefore{\textbf{before}~} -\def\enafter{\textbf{after}~} -\DeclareDocumentEnvironment { note } { +b } { - \par\textbf{\textsf{NOTE:~}}#1\par -} {} - -\AtEndDocument{ - \newgeometry{ - left=2cm, - right=2cm, - top=2cm, - bottom=2cm - } - \PrintChanges - \PrintIndex -} - -\ExplSyntaxOn -\makeatletter -\cs_new_protected:Nn \dbshow_changes:nnnn { - \@bsphack\group_begin:\@sanitize - \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore - \exp_args:Nx \glossary { - \exp_not:N \textbf{#1}\levelchar - \exp_not:N \textit{#2}\c_space_tl - \exp_not:N \textbf{#3}\c_colon_str\c_space_tl - \exp_not:n { #4 } - } - \group_end:\@esphack -} -\cs_generate_variant:Nn \dbshow_changes:nnnn { xnnn } - -\cs_new_protected:Nn \dbshow_changes_what:nnnn { - \regex_extract_once:nnNT { doc|macro|bug|option } - { #3 } \l_tmpa_seq { - \dbshow_changes:xnnn { - \str_case_e:nn { \seq_item:Nn \l_tmpa_seq { 1 } } { - { doc } { Documentation } - { macro } { Macro } - { bug } { Bug } - { option } { Option } - { logic } { Logic } - } - } - {#2} {#3} {#4} - } -} - -\cs_new_protected:Nn \dbshow_changes_how:nnnn { - \regex_extract_once:nnNT { Add|Update|Remove } { #3 } \l_tmpa_seq { - \dbshow_changes:xnnn { \seq_item:Nn \l_tmpa_seq { 1 } } - {#2} {#3} {#4} - } -} - -% #1 version #2 date #3 type #4 desc -\DeclareDocumentCommand \changes { m m m m } { - \dbshow_changes:nnnn {#1} {#2} {#3} {#4} - \dbshow_changes_what:nnnn {#1} {#2} {#3} {#4} - \dbshow_changes_how:nnnn {#1} {#2} {#3} {#4} -} -\makeatother - -\DeclareDocumentEnvironment { Description } { o +b } { - \hbox_set:Nn \l_tmpa_box { #1 } - \dim_set:Nn \l_tmpa_dim { \box_wd:N \l_tmpa_box } - \begin{itemize}[labelwidth=\l_tmpa_dim, align=left] - #2 - \end{itemize} -} { } - -\cs_new_protected:Nn \dbshowdoc_function_begin:N { - \cs_set_eq:NN \__codedoc_tmp_cs:nN \__codedoc_typeset_function_block:nN - \cs_set_protected:Npn \__codedoc_typeset_function_block:nN ##1##2 { - \__codedoc_function_label:xN {##1} ##2 - \hbox_set:Nn \l_tmpa_box {##1} - \int_compare:nTF { \str_count:n {##1} <= 22 } - {##1} { \adjustbox{width=.7\marginparwidth, height=\box_ht:N \l_tmpa_box}{##1} } - #1{##1} - \__codedoc_typeset_expandability: \\ - } -} -\cs_new_protected:Nn \dbshowdoc_function_end: { - \cs_set_eq:NN \__codedoc_typeset_function_block:nN \__codedoc_tmp_cs:nN -} -\DeclareDocumentEnvironment { option } { O{} +v } - { - \dbshowdoc_function_begin:N \SpecialOptionIndex - \__codedoc_function:nnw {#1} {#2} - } - { - \__codedoc_function_end: - \dbshowdoc_function_end: - } -\DeclareDocumentEnvironment { environment } { O{} +v } - { - \dbshowdoc_function_begin:N \SpecialEnvIndex - \__codedoc_function:nnw {#1} {#2} - } - { - \__codedoc_function_end: - \dbshowdoc_function_end: - } - -\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} 宏包 \version% - \protect\footnote{% - 代码仓库:\url{https://github.com/ZhiyuanLck/dbshow}, - QQ群:788706534} - \rlap{\makebox[4cm][r]{ - \normalsize $\Longrightarrow$ \color{red} - \linktarget{en}{zh}{English Version} - }} -} -\author{\textit{李昌锴} \texttt{<lichangkai225@qq.com>}} -\date{\zhdate} -\maketitle - -\tableofcontents - -\begin{documentation} - -\section{引言} -编写本宏包的动机来源于当前没有一个很好的错题本宏包,可以方便的根据各种条件对错 -题进行筛选、排序,然后以自定义的样式展示出来。\pkg{dbshow} 宏包实现了四个核心 -功能:数据存储和使用、数据筛选、数据排序、数据展示。 - -数据只需要存储一次,就可以通过预定义的筛选、排序条件和样式展示部分或全部的数据。 -如上所述,本宏包其实实现了一个非常简单的数据库,复习错题的功能只是其中一个应用, -和其他数据库宏包比如 \pkg{datatool} 相比,\pkg{dbshow} 更专注于非图表类型的数 -据展示。 - -\changes{1.2}{2022-01-09}{Add doc}{descripton for expansion} -\begin{itemize} - \item 名字后带有 $\star$ 的命令是可以完全展开的(fully-expandable); - \item 名字后带有 \ding{73} 的命令可以有限制地展开(restricted-expandable); - \item 名字后不带有特殊字符的命令是不可展开的(non-expandable); - \item 名字后带有 $\star$ 的选项不影响相关的代码的是否可展开; - \item 名字后带有 \ding{73} 的选项是否影响相关代码的可展开性取决于选项的设置; - \item 名字后不带有特殊字符的选项会使与之相关的代码变得不可展开。 -\end{itemize} - -\subsection{数据类型} - -宏包基于 \pkg{expl3} 的基础类型构建了6种类型: -\begin{Description}[\texttt{clist}] - \item[\texttt{date}] - 日期类型,以 |yyyy/mm/dd| 形式存储,支持大小比较,排序(转 - 换成字符串)。默认值为 \cs{dbtoday}。 - \item[\texttt{str}] - 字符串类型,支持正则匹配,英文排序。默认值为空。 - \item[\texttt{tl}] - \meta{token list}类型,支持正则匹配。默认值为空。 - \item[\texttt{int}] - 整数类型,支持大小比较,排序。默认值为0。 - \item[\texttt{fp}] - 浮点数类型,支持大小比较,排序。默认值为0。 - \item[\texttt{clist}] - 逗号分隔的列表类型。默认值为空列表。 -\end{Description} - -\changes{1.3}{2022-01-08}{Remove dependency}{\pkg{datatime2}} -除了日期类型,所有类型都是 \pkg{expl3} 的内置类型。\pkg{dbshow} 构建了一个简单 -的 |date| 类型,支持转换成整数以及带样式的打印。 - -\subsection{与 \pkg{datatool} 的区别} - -\changes{1.2}{2022-01-07}{Add doc}{add comparison to \pkg{datatool}} - -从核心功能上看,\pkg{dbshow} 和 \pkg{datatool} 实现了相同的功能。区别在于 -\pkg{dbshow} 基于 \pkg{expl3} 实现,支持字符串的正则匹配,还支持多级排序。使用 -方式上更倾向于样式与内容分离,所有的样式都可以通过选项提前定义好并且可以复用。 -\pkg{dbshow} 并没有实现从外部文件读取数据以及将数据持久化的功能,我认为这些应 -该是更专业的外部程序的工作而不应该在 \LaTeX 中设计这些功能。因此,\pkg{dbshow} -只提供了一个运行时的临时数据库,足够轻便且满足大部分正常需求。如果你想删除或修 -改数据库中某一条记录,请去对应的位置删除或修改掉对应的 \env{dbitem} 环境,而不 -是让宏包提供一个输出某一行记录的命令。某种意义上记录数据库的 \TeX 源文件本身就 -是数据的一种持久化。 - -\section{接口文档} - -\subsection{创建、展示和清空数据库} -\begin{function}[added=2022-01-05]{\dbNewDatabase, \dbNewDatabase*} - \begin{syntax} - \cs{dbNewDatabase} \oarg{base database} \marg{database} \{ \\ - ~~\meta{attr1} = \meta{type spec1}, \\ - ~~\meta{attr2} = \meta{type spec2}, \\ - ~~\ldots{} \\ - \} \\ - \cs{dbNewDatabase}* \marg{database} \{ \\ - ~~\meta{attr1} = \meta{type spec1}, \\ - ~~\meta{attr2} = \meta{type spec2}, \\ - ~~\ldots{} \\ - \} \\ - \end{syntax} - -\end{function} - - 新建一个数据库,不带星号的版本可以指定一个数据库来继承其属性设置,该版本总是 - 会舍弃掉之前的定义。 - - 带星号的版本不会舍弃之前已有的定义,而是将新的选项添加到后面。 - - \meta{attr} 为属性名称,\meta{type spec} 负责声明属性类型和属性默认值: - - \noindent\begin{tblr}{ - colspec = {ll}, - column{1} = {font = \ttfamily} - } - \meta{attr} = \meta{type} & - 将 \meta{attr} 声明为 \meta{type} 类型 \\ - \meta{attr} = \meta{type}\orbar\meta{default} & - 将 \meta{attr} 声明为 \meta{type} 类型,并且将默认值设置为 \meta{default}。 - \\ - \end{tblr} - - \begin{note} - 每个数据库都有一个默认的属性 |id| 用来存储数据的索引。 - \end{note} - - 下面是定义一个错题数据库的示例,|question| 和 |answer| 属性用来存储问题和答 - 案,|date| 属性存储日期,|info| 属性存储额外信息,|labels| 存储题目标签。 -\begin{verbatim} - \dbNewDatabase{ques}{ - question = tl, - answer = tl, - date = date, - info = tl, - labels = clist - } -\end{verbatim} - -\begin{function}[added=2022-01-05]{\dbshow} - \begin{syntax} - \cs{dbshow} \marg{style} \marg{database} - \end{syntax} - - 使用 \meta{style} 样式来展示 \meta{database}。 -\end{function} - -\changes{1.2}{2022-01-07}{Add macro}{\cs{dbclear}} -\begin{function}[added=2022-01-07]{\dbclear} - \begin{syntax} - \cs{dbclear} \marg{database} - \end{syntax} - 清空 \meta{database} 里的所有内容。 -\end{function} - -\subsection{\cs{dbNewStyle} 和样式选项} - -\begin{function}[added=2022-01-05]{\dbNewStyle} - \begin{syntax} - \cs{dbNewStyle} \oarg{base styles} \marg{style} \marg{database} \marg{opts} - \end{syntax} - - 为 \meta{database} 定义一个新的样式 \meta{style},该样式可以基于已有的样式 - \meta{base styles},比如 |\dbNewStyle[base1, base2]{new-style}{ques}{}|。 -\end{function} - -\subsubsection{通用选项} - -\begin{option}[added=2022-01-05]{filter} - \begin{syntax} - filter = <filter> - \end{syntax} - - 为当前样式设置由 \cs{dbCombineFilters} 所定义的过滤器 -\end{option} - -\begin{option}[added=2022-01-06]{raw-filter} - \begin{syntax} - raw-filter = <conditional expression> - \end{syntax} - - 使用条件表达式设置匿名过滤器,这里的条件指通过 \cs{dbNewConditional} 定义的 - 条件。下面代码中两个示例的过滤器具有相同的功能。 -\end{option} - -\changes{1.1}{2022-01-06}{Add option}{\opt{raw-filter}} - -\begin{verbatim} - % method 1 - \begin{dbFilters}{db} - \dbNewConditional{cond1}{int-attr}{\rval > 1} - \dbNewConditional*{cond2}{str-attr}{\d+} - \end{dbFilters} - \dbNewStyle{style}{db}{raw-filter={cond1 && cond2}} - % method 2 - \begin{dbFilters}{db} - \dbNewConditional{cond1}{int-attr}{\rval > 1} - \dbNewConditional*{cond2}{str-attr}{\d+} - \dbCombineFilters{filter}{cond1 && cond2} - \end{dbFilters} - \dbNewStyle{style}{db}{filter=filter} -\end{verbatim} - -\changes{1.2}{2022-01-08}{Fix bug}{string sorting bug} -\begin{option}[added=2022-01-05]{sort} - \begin{syntax} - sort = \{ <attr spec1>, <attr spec2>, \ldots{} \} - \end{syntax} - - 为当前样式设置排序规则。支持根据 |str|,|date|,|int|,|fp| 类型的数据进行排 - 序,支持多级排序。\meta{attr} 表示增序,\meta{attr}* 表示降序。下面例子中, - 使用 |sort-style| 展示数据时的顺序为先按 |level| 降序,|level| 相同的再按出 - 生日期 |birth| 增序,以此类推。 -\end{option} - -\begin{verbatim} - \dbNewDatabase{sort-example}{ - name = str, - birth = date, - level = int, - weight = fp, - } - \dbNewStyle{sort-style}{sort-example}{ - sort = { level*, birth, name, weight } - } -\end{verbatim} - -\begin{option}[added=2022-01-05, rEXP]{item-code} - \begin{syntax} - item-code = <code> - \end{syntax} - - 该选项用来设置展示数据库中每条记录的代码。你可以使用 \cs{dbuse} 来展示属性的 - 值。 -\end{option} - -\changes{1.3}{2022-01-09}{Update option}{\opt{<attr>/sep}} -\begin{option}[added=2022-01-05, updated=2022-01-08, rEXP]{<attr>/sep} - \begin{syntax} - <attr>/sep = <separator> \\ - <attr>/sep = \{ \\ - ~~\meta{separator between two}, \\ - ~~\meta{separator between more than two}, \\ - ~~\meta{separator between final two} \\ - \} \\ - <attr>/sep = \{ \\ - ~~\meta{separator before year}, \\ - ~~\meta{separator between year and month}, \\ - ~~\meta{separator between month and day}, \\ - ~~\meta{separator after day} \\ - \} \\ - \end{syntax} - - 该选项只适用于类型为 |clist| 或 |date| 的属性,用来设置列表间元素的间隔。参 - 数为一个 \meta{separator} 时,所有元素间的分隔符被设置为 \meta{separator}。 - \meta{separator before year} 和 \meta{separator after day} 被设置为空。 -\end{option} - - 参数为3个元素的逗号分隔的列表时,此选项用来设置列表元素的分隔符,分别用来设 - 置只有两个元素时的分隔符 \meta{separator between two},超过两个元素时的分隔 - 符 \meta{separator between more than two},和最后两个元素之间的分隔符 - \meta{separator between final two}。对于类型为 |clist| 的属性,设置此选项时 - 如果参数列表数量不是1或者3会触发报错。 - -\begin{verbatim} - % clist-attr is an attribute of database db - % suppose the val of clist-attr is { 1, 2, 3 } - \dbNewStyle{clist-sep}{db}{ - clist-attr/sep = { ,~ }, % print 1, 2, 3 - clist-attr/sep = { {,~}, {,~}, {and~} } % print 1, 2 and 3 - } -\end{verbatim} - - 参数为4个元素的逗号分隔的列表时,此选项用来设置日期的分隔符,分别用来设 - 置 \meta{year} 之前的分隔符 \meta{separator before year} ,\meta{year} 和 - \meta{month} 之间的分隔符 \meta{separator between year and month} , - \meta{month} 和 \meta{day} 之间的分隔符,以及 \meta{day} 之后的分隔符。对于 - 类型为 |date| 的属性,设置此选项时如果参数列表数量不是1或者4会触发报错。 - -\begin{verbatim} - % date-attr is an attribute of database db - % suppose the val of date-attr is 2022/01/01 - \dbNewStyle{date-sep}{db}{ - date-attr/sep = -, % print 2022-01-01 - date-attr/sep = { |, -, -, | } % print |2022-01-01| - } -\end{verbatim} - -\changes{1.3}{2022-01-08}{Add option}{\opt{<attr>/zfill}} -\begin{option}[added=2022-01-08, EXP]{<attr>/zfill} - \begin{syntax} - <attr>/zfill = <\TTF> - \end{syntax} - - 该选项只适用于类型为 |date| 的属性。控制输出月份和天时是否补零。 -\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} - -\changes{1.3}{2022-01-08}{Add option}{\opt{<attr>/wrapper}} -\begin{option}[added=2022-01-08, rEXP]{<attr>/wrapper} - \begin{syntax} - <attr>/wrapper = <control sequence> - \end{syntax} - - 该选项只适用于类型为 |date| 的属性。\meta{control sequence} 只接收一个参数即 - 日期,如果设置了此选项,则最后输出的日期为 - \meta{control sequence}\marg{date}。 -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{before-code} - \begin{syntax} - before-code = <code> - \end{syntax} - - 该选项用来设置在展示整个数据库之\zhbefore 需要执行的代码。 -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{after-code} - \begin{syntax} - after-code = <code> - \end{syntax} - - 该选项用来设置在展示整个数据库之\zhafter 需要执行的代码。 -\end{option} - -\changes{1.2}{2022-01-08}{Add options}{\opt{record-before-code}, -\opt{record-after-code}} -\begin{option}[added=2022-01-05, rEXP]{record-before-code} - \begin{syntax} - record-before-code = <code> - \end{syntax} - - 该选项用来设置在展示当前记录之\zhbefore 需要执行的代码。 -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{record-after-code} - \begin{syntax} - record-after-code = <code> - \end{syntax} - - 该选项用来设置在展示当前记录之\zhafter 需要执行的代码。 -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{<attr>/before-code} - \begin{syntax} - <attr>/before-code = <code> - \end{syntax} - - 该选项用来设置展示数据库中属性 \meta{attr} 对应数据之\zhbefore 需要执行的代 - 码。\cs{dbuse} 会在展示属性数据\zhbefore 执行此代码。 -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{<attr>/after-code} - \begin{syntax} - <attr>/after-code = <code> - \end{syntax} - - 该选项用来设置展示数据库中属性 \meta{attr} 对应数据之\zhafter 需要执行的代码。 - \cs{dbuse} 会在展示属性数据\zhafter 执行此代码。 -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{<attr>/item-before-code} - \begin{syntax} - <attr>/item-before-code = <code> - \end{syntax} - - 该选项只适用于类型为 |clist| 的属性,用来设置展示列表每个元素\zhbefore 需要 - 执行的代码。 -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{<attr>/item-after-code} - \begin{syntax} - <attr>/item-after-code = <code> - \end{syntax} - - 该选项只适用于类型为 |clist| 的属性,用来设置展示列表每个元素\zhafter 需要执 - 行的代码。 -\end{option} - -\subsection{使用 \cs{dbNewReviewPoints} 定义复习点} - -\begin{function}[added=2022-01-05]{\dbNewReviewPoints} - \begin{syntax} - \cs{dbNewReviewPoints} \marg{name} \marg{points} - \end{syntax} - - 定义名为 \meta{name} 的复习点。这是专门为错题本或复习所定制的功能, - \meta{points}是一系列整数,现在假设每道错题你都将写错时的日期记录在了 |date| - 属性中,并且你希望每隔2,5,15天复习一次。下面的代码给出了一个实现示例。 -\end{function} - -\begin{verbatim} - \dbNewReviewPoints{review-point}{2, 5, 15} % 定义复习点 - \begin{dbFilters} - \dbNewConditional{cond1}{date}{review-point|\Today} % 定义复习条件 - \dbCombineConditionals{filter1}{cond1} % 定义过滤器 - \end{dbFilters} - \dbNewStyle{review-style}{ques}{filter=filter1} % 定义展示样式 -\end{verbatim} - -\subsection{在 \env{dbFilters} 环境中定义过滤器} - -\begin{environment}[added=2022-01-05]{dbFilters} - \begin{syntax} - |\begin{dbFilters}|\marg{database} \\ - ~~\meta{code} - |\end{dbFilters}| \\ - \end{syntax} - - \env{dbFilters}用来定义过滤器,此环境中定义了 \cs{dbNewConditional} 命令用来 - 定义条件和 \cs{dbCombineConditionals} 命令用来组合条件定义过滤器。过滤器独立 - 于每个 \meta{database},这意味着你可以在不同数据库中定义名称相同的过滤条件和 - 过滤器。 -\end{environment} - -\begin{function}[added=2022-01-05, updated=2022-01-08]{\dbNewConditional, \dbNewConditional*} - \begin{syntax} - \cs{dbNewConditional} \marg{name} \marg{attr} \marg{cond spec} \\ - \cs{dbNewConditional}* \marg{name} \marg{attr} \marg{cond spec} \\[2pt] - \cs{dbNewConditional} \marg{name} \marg{int/fp attr} \marg{expr} \\ - \cs{dbNewConditional}* \marg{name} \marg{int/fp attr} \marg{expr} \\ - \cs{dbNewConditional} \marg{name} \marg{str/tl attr} \marg{regex expr} \\ - \cs{dbNewConditional}* \marg{name} \marg{str/tl attr} \marg{regex expr} \\ - \cs{dbNewConditional} \marg{name} \marg{clist attr} \marg{val list} \\ - \cs{dbNewConditional}* \marg{name} \marg{clist attr} \marg{val list} \\ - \cs{dbNewConditional} \marg{name} \marg{date attr} \marg{expr} - \cs{dbNewConditional}* \marg{name} \marg{date attr} \{\meta{review points}\orbar\meta{date}\} \\ - \end{syntax} - - \cs{dbNewConditional} 用来定义名为 \meta{name} 的条件,\meta{attr} 指定条件 - 所绑定的属性,在 \meta{cond spec} 中可以用 \cs{dbval} 指代属性的值。 -\end{function} - - \changes{1.3}{2022-01-10}{Update doc}{truncated division} - 对于类型为 |int| 和 |fp| 的属性,\meta{expr} 传递给 \cs{int_compare:nTF} 或 - \cs{fp_compare:nTF} 处理。 - \begin{note} - |/| 为四舍五入除法,截断除法请用 \cs{dbIntDivTruncate}。 - \end{note} - - 对于类型为 |str| 和 |tl| 的属性,\meta{regex} 为正则表达式, - \cs{dbNewConditional} 表示部分匹配,\cs{dbNewConditional*} 表示整体匹配。 - -\begin{verbatim} - \dbNewConditional {cond1}{str-attr}{abc} % 匹配 abc, abcd, 1abc, =abc= 等 - \dbNewConditional*{cond2}{str-attr}{abc} % 只匹配 abc -\end{verbatim} - - 对于类型为 |clist| 的属性,使用 \cs{dbNewConditional} 定义的条件只要 - \meta{val list} 中的任意一个元素在属性值(列表)中则条件成立;使用 - \cs{dbNewConditional*} 定义的条件只有 \meta{val list} 中每一个值都在属性值 - (列表)中条件才成立。 - -\begin{verbatim} - \dbNewConditional {cond1}{clist-attr}{a, b, c} % a, b, d 满足条件 - \dbNewConditional*{cond2}{clist-attr}{a, b, c} % a, b, d 不满足条件 -\end{verbatim} - - \changes{1.3}{2022-01-08}{Update logic}{swap definition of starred and - unstarred conditionals of date} - 对于类型为 |date| 的属性,\cs{dbNewConditional} 定义的条件后续处理中会将 - \meta{expr} 中的所有日期转换成相对\textit{1971年1月1日}的一个整数值,然后将 - 处理后的表达式传递给 \cs{int_compare:nTF} 做进一步处理; - \cs{dbNewConditional*} 使用复习点来定义过滤条件,\meta{review points} 是 - \cs{dbNewReviewPoints} 定义的复习点,\meta{date} 是用来比较的日期。 - -\begin{function}[added=2022-01-05]{\dbCombineConditionals} - \begin{syntax} - \cs{dbCombineConditionals} \marg{name} \marg{cond combination} \oarg{info} - \end{syntax} - - \cs{dbCombineConditionals} 定义名为 \marg{name} 的过滤器,并将 - \cs{dbNewConditional} 定义的条件组合起来,比如 - \verb=\dbCombineConditionals{filter}{(cond1 && cond2) || !cond3}=。 - \meta{cond combination} 中可以使用的关系操作符为 \verb=&&, ||, !=。 - 可以将 \opt{filter} 选项设置为 \meta{name} 来应用过滤器。\meta{info} 为过滤 - 器的相关信息,在展示数据库的时候可以用 \cs{dbFilterInfo} 指代。 -\end{function} - -\subsection{使用 \env{dbitem} 环境存储数据} - -\begin{environment}[added=2022-01-05]{dbitem} - \begin{syntax} - |\begin{dbitem}|\marg{database}[ \\ - ~~\meta{attr1} = \meta{val1}, \\ - ~~\meta{attr2} = \meta{val2}, \\ - ~~\ldots{} \\ - ] \\ - ~~\meta{code} \\ - |\end{dbitem}| - \end{syntax} - - \env{dbitem} 环境用来存储数据。有两种存储数据的方法,较短的数据可以在选项列 - 表中通过键值对设置值,较长的数据可以在 \meta{code} 中使用 \cs{dbsave} 存储。 - \cs{dbsave}会覆盖选项中设置的值。没有设置的值将会被设置为全局默认值,下面给 - 出一个存储示例。 -\end{environment} - -\begin{verbatim} - \begin{dbitem}[date = 2022-01-01, info = 测试] - \dbsave{question}{这是一个测试问题} - \dbsave{answer} {这是一个测试答案} - \end{dbitem} -\end{verbatim} - -\subsection{\cs{dbsave} 和 \cs{dbuse}} - -\changes{1.3}{2022-01-08}{Add macro}{\cs{dbsave*}} -\begin{function}[added=2022-01-05, updated=2022-01-08]{\dbsave, \dbsave*} - \begin{syntax} - \cs{dbsave} \marg{attr} \marg{data} \\ - \cs{dbsave}* \marg{attr} \marg{data} - \end{syntax} - - \cs{dbsave} 用来存储数据,只能在 \env{item} 环境中使用。使用 \cs{dbsave*} 存 - 储的数据会被 \cs{exp_not:n} 包裹。 -\end{function} - -\changes{1.2}{2022-01-08}{Update macro}{make \cs{dbuse} fully-expandable} -\begin{function}[added=2022-01-05, updated=2022-01-08, EXP]{\dbuse} - \begin{syntax} - \cs{dbuse} \marg{attr} - \end{syntax} - - \cs{dbuse} 用来展示数据,只能在 \opt{item-code} 选项中使用。\cs{dbuse} 是可 - 展开的。 -\end{function} - -\subsection{条件判别式} - -\begin{function}[added=2022-01-05, EXP]{\dbIfEmptyT, \dbIfEmptyF, \dbIfEmptyTF} - \begin{syntax} - \cs{dbIfEmptyTF} \marg{true code} \marg{false code} \\ - \cs{dbIfEmptyT} \marg{true code} \\ - \cs{dbIfEmptyF} \marg{false code} - \end{syntax} - - 该判别式用来判断当前数据库是否为空。下面的示例展示了如何预防空的列表环境。 -\end{function} - -\begin{verbatim} - \dbNewStyle{style-cond1}{database-test}{ - before-code = {\dbIfEmptyF{\begin{enumerate}}}, - after-code = {\dbIfEmptyF{\end{enumerate}}}, - item-code = {\item \dbuse{attr-test}} - } -\end{verbatim} - -\changes{1.2}{2022-01-08}{Remove macros}{\cs{dbItemIfEmpty(TF)}, \cs{dbClistItemIfEmpty(TF)}} - -\subsection{表达式函数} - -\changes{1.3}{2022-01-10}{Add macros}{expression function aliases} -\begin{function}[added=2022-01-10, EXP]{ - \dbIntAbs, \dbIntSign, \dbIntDivRound, \dbIntDivTruncate, \dbIntMax, - \dbIntMin, \dbIntMod, \dbFpSign, -} - \begin{syntax} - \cs{dbIntAbs} \Arg{intexpr} - \cs{dbIntSign} \Arg{intexpr} - \cs{dbIntDivRound} \Arg{intexpr_1} \marg{intexpr_2} - \cs{dbIntDivTruncate} \Arg{intexpr_1} \marg{intexpr_2} - \cs{dbIntMax} \Arg{intexpr_1} \marg{intexpr_2} - \cs{dbIntMin} \Arg{intexpr_1} \marg{intexpr_2} - \cs{dbIntMod} \Arg{intexpr_1} \marg{intexpr_2} - \cs{dbFpSign} \Arg{fpexpr} - \end{syntax} - \cs{dbIntAbs} 等同于 \cs{int_abs:n} \\ - \cs{dbIntSign} 等同于 \cs{int_sign:n} \\ - \cs{dbIntDivRound} 等同于 \cs{int_div_round:nn} \\ - \cs{dbIntDivTruncate} 等同于 \cs{int_div_truncate:nn} \\ - \cs{dbIntMax} 等同于 \cs{int_max:nn} \\ - \cs{dbIntMin} 等同于 \cs{int_min:nn} \\ - \cs{dbIntMod} 等同于 \cs{int_mod:nn} \\ - \cs{dbFpSign} 等同于 \cs{fp_sign:n} \\ - 详细的文档见 \pkg{interface3} \\ -\end{function} - -\subsection{特殊命令} - -\pkg{dbshow} 定义了一些特殊的命令,会根据语境展开为不同的内容。 - -\changes{1.1}{2022-01-05}{Add macro}{ - \cs{dbarabic}, \cs{dbalph}, \cs{dbAlph}, \cs{dbroman}, - \cs{dbRoman} -} -\changes{1.1}{2022-01-06}{Fix bug}{\cs{dbIndex} not defined} -\begin{function}[added=2022-01-05, EXP]{ - \dbval, \dbDatabase, \dbFilterName, \dbFilterInfo, - \dbIndex, \dbarabic, \dbalph, \dbAlph, \dbroman, \dbRoman -} -\begin{tblr}{ll} - \cs{dbval} & 当前属性的值 \\ - \cs{dbDatabase} & 数据库名称 \\ - \cs{dbFilterName} & 当前样式过滤器的名称 \\ - \cs{dbFilterInfo} & 当前样式过滤器的相关信息 \\ - \cs{dbIndex} & 数据索引,等同于 \cs{dbuse}|{id}| \\ - \cs{dbarabic} & 用数字表示的查询集数据计数 \\ - \cs{dbalph} & 用小写字母表示的查询集数据计数 \\ - \cs{dbAlph} & 用大写字母表示的查询集数据计数 \\ - \cs{dbroman} & 用小写罗马字母表示的查询集数据计数 \\ - \cs{dbroman} & 用大写罗马字母表示的查询集数据计数 \\ - \end{tblr} -\end{function} - -\section{错题本示例} -见第 \ref{sec:example} 节。 - -\changes{1.1}{2022-01-07}{Update doc}{improve example} - -\title{ - 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} - \linktarget{zh}{en}{中文版本} - }} -} -\author{Li Changkai \texttt{<lichangkai225@qq.com>}} -\date{\endate} -\maketitle - -\section{Introduction} - -The initial motivation to write this package is that I want to write a -template, which can collect questions you gave the wrong answer and can -display those questions you would like to review by some conditionals, such as -questions with certain label, questions you have answered uncorrectly for -certain times or questions having not been reviewed for certain days. So this -package provides a database to do such thing. - -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. - -\changes{1.2}{2022-01-09}{Add doc}{descripton for expansion} -\begin{itemize} - \item Macros with a $\star$ are fully-expandable; - \item Macros with a \ding{73} are restricted-expandable; - \item Macros without appending a special symbol are nonexpandable; - \item Options with a $\star$ \textit{do not} affect the expandability of - related macros; - \item Options with a \ding{73} affect the expandability of related macros - according to its value; - \item Options without appending a special symbol make the related macros - nonexpandable. -\end{itemize} - -\subsection{Data Types} - -The package constructs 6 types based on the internal typed of \pkg{expl3}: -\begin{Description}[\texttt{clist}] - \item[\texttt{date}] - date saved in |yyyy/mm/dd| format, supports comparison, sorting - (converting to string), default \cs{dbtoday}. - \item[\texttt{str}] - string,supports regex match and sorting, default empty. - \item[\texttt{tl}] - token list, supports regex match, default empty. - \item[\texttt{int}] - integer, supports comparison and sorting, default 0. - \item[\texttt{fp}] - floating point, supports comparison and sorting, default 0. - \item[\texttt{clist}] - comma list, default empty. -\end{Description} - -\changes{1.3}{2022-01-08}{Remove dependency}{\pkg{datatime2}} -All types are internal types of \pkg{expl3} except |date| type, which provides -by \pkg{dbshow} itself and supports converting to integer and printing with -style. - -\subsection{Comparison to \pkg{datatool}} - -\changes{1.2}{2022-01-07}{Add doc}{add 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{Create, Display and Clear Database} - -\begin{function}[added=2022-01-05]{\dbNewDatabase, \dbNewDatabase*} - \begin{syntax} - \cs{dbNewDatabase} \oarg{base database} \marg{database} \{ \\ - ~~\meta{attr1} = \meta{type spec1}, \\ - ~~\meta{attr2} = \meta{type spec2}, \\ - ~~\ldots{} \\ - \} \\ - \cs{dbNewDatabase}* \marg{database} \{ \\ - ~~\meta{attr1} = \meta{type spec1}, \\ - ~~\meta{attr2} = \meta{type spec2}, \\ - ~~\ldots{} \\ - \} \\ - \end{syntax} - -\end{function} - -Create a new database named \meta{database}, unstarred form provides the optional -\meta{base database} from which current database inherit the attributes settings. -The unstarred form always replace the old definition, while starred form -appends the new options. - -\begin{syntax} - \meta{attr} = \meta{type} \\ - \meta{attr} = \meta{type}\orbar\meta{default} -\end{syntax} - -The first form defines the \meta{attr} as \meta{type}, and the second also -sets the default value. - -\begin{note} - Every database has a default attribute |id| to store the index of the item. -\end{note} - -The example below define a database named |ques|. -\begin{verbatim} - \dbNewDatabase{ques}{ - question = tl, % store question - answer = tl, % store corresponding answer - date = date, % store the date when you were wrong - info = tl, % store extra info - labels = clist % store question labels - } -\end{verbatim} - -\begin{function}[added=2022-01-05]{\dbshow} - \begin{syntax} - \cs{dbshow} \marg{style} \marg{database} - \end{syntax} - - Show the \meta{database} with \meta{style}. -\end{function} - -\changes{1.2}{2022-01-07}{Add macro}{\cs{dbclear}} -\begin{function}[added=2022-01-07]{\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}[added=2022-01-05]{\dbNewStyle} - \begin{syntax} - \cs{dbNewStyle} \oarg{base styles} \marg{style} \marg{database} \marg{opts} - \end{syntax} - - Define a new \meta{style} that binds to \meta{database}. The style can - inherit from a list of \meta{base styles} such as - |\dbNewStyle[base1, base2]{new-style}{ques}{}|. -\end{function} - -\subsubsection{General Options} - -\begin{option}[added=2022-01-05]{filter} - \begin{syntax} - filter = <filter> - \end{syntax} - - Set the \meta{filter} defined by \cs{dbCombineFilters}. -\end{option} - -\changes{1.1}{2022-01-06}{Add option}{\opt{raw-filter}} -\begin{option}[added=2022-01-06]{raw-filter} - \begin{syntax} - raw-filter = <conditional expression> - \end{syntax} - - Set anonymous with conditionals defined by \cs{dbNewConditional}. Two - filters shows in the code below have the same meaning. -\end{option} - -\begin{verbatim} - % method 1 - \begin{dbFilters}{db} - \dbNewConditional{cond1}{int-attr}{\rval > 1} - \dbNewConditional*{cond2}{str-attr}{\d+} - \end{dbFilters} - \dbNewStyle{style}{db}{raw-filter={cond1 && cond2}} - % method 2 - \begin{dbFilters}{db} - \dbNewConditional{cond1}{int-attr}{\rval > 1} - \dbNewConditional*{cond2}{str-attr}{\d+} - \dbCombineFilters{filter}{cond1 && cond2} - \end{dbFilters} - \dbNewStyle{style}{db}{filter=filter} -\end{verbatim} - -\changes{1.2}{2022-01-08}{Fix bug}{string sorting bug} -\begin{option}[added=2022-01-05]{sort} - \begin{syntax} - sort = \{ <attr spec1>, <attr spec2>, \ldots{} \} - \end{syntax} - - Set sorting rules. Attributes of type |str, date, int, fp| is supported to - sort. Multi-level sort is allowed. \meta{attr} represents for ascending - order, and \meta{attr}* represents for descending order. The example below - use four fields to determine the order of the records. It sorts on |level| - in descending order first and if two |levels| are same then sorts on |birth| - in ascending order and so on. -\end{option} - -\begin{verbatim} - \dbNewDatabase{sort-example}{ - name = str, - birth = date, - level = int, - weight = fp, - } - \dbNewStyle{sort-style}{sort-example}{ - sort = { level*, birth, name, weight } - } -\end{verbatim} - -\begin{option}[added=2022-01-05, rEXP]{item-code} - \begin{syntax} - item-code = <code> - \end{syntax} - - Set the code that show a single record. You can use \cs{dbuse} to display - certian attribute. -\end{option} - -\changes{1.3}{2022-01-09}{Update option}{\opt{<attr>/sep}} -\begin{option}[added=2022-01-05, updated=2022-01-08, rEXP]{<attr>/sep} - \begin{syntax} - <attr>/sep = <separator> \\ - <attr>/sep = \{ \\ - ~~\meta{separator between two}, \\ - ~~\meta{separator between more than two}, \\ - ~~\meta{separator between final two} \\ - \} \\ - <attr>/sep = \{ \\ - ~~\meta{separator before year}, \\ - ~~\meta{separator between year and month}, \\ - ~~\meta{separator between month and day}, \\ - ~~\meta{separator after day} \\ - \} \\ - \end{syntax} - - Only for attributes of type |clist| or |date|. Set the separator between - items. If the argument is an one-item comma list, all separators are set to - \meta{separator} but \meta{separator before year} and \meta{separator after - day} is set empty. -\end{option} - - If the argument is a comma list of 3 items, it is used to set the separator - between items of the comma list. Following documentation is quoted from - \pkg{interface3}: - \begin{quote} - If the comma list has more than two items, the \meta{separator between - more than two} is placed between each pair of items except the last, for - which the \meta{separator between final two} is used. If the comma list - has exactly two items, then they are placed in the input stream separated - by the \meta{separator between two}. If the comma list has a single item, - it is placed in the input stream, and a comma list with no items produces - no output. - \end{quote} - For attributes of type |clist|, incorrect number (numbers exclude 1 and 3) - of items of the argument will raise an error. - -\begin{verbatim} - % clist-attr is an attribute of database db - % suppose the val of clist-attr is { 1, 2, 3 } - \dbNewStyle{clist-sep}{db}{ - clist-attr/sep = { ,~ }, % print 1, 2, 3 - clist-attr/sep = { {,~}, {,~}, {and~} } % print 1, 2 and 3 - } -\end{verbatim} - - If the argument is a comma list of 4 items, it is used to set the separators - of the date. For attributes of type |date|, incorrect number (numbers - exclude 1 and 4) will raise an error. - -\begin{verbatim} - % date-attr is an attribute of database db - % suppose the val of date-attr is 2022/01/01 - \dbNewStyle{date-sep}{db}{ - date-attr/sep = -, % print 2022-01-01 - date-attr/sep = { |, -, -, | } % print |2022-01-01| - } -\end{verbatim} - -\changes{1.3}{2022-01-08}{Add option}{\opt{<attr>/zfill}} -\begin{option}[added=2022-01-08, EXP]{<attr>/zfill} - \begin{syntax} - <attr>/zfill = <\TTF> - \end{syntax} - - Only for attributes of type |date|. Control whether to fill zero on the left - of the month or day. -\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} - -\changes{1.3}{2022-01-08}{Add option}{\opt{<attr>/wrapper}} -\begin{option}[added=2022-01-08, rEXP]{<attr>/wrapper} - \begin{syntax} - <attr>/wrapper = <control sequence> - \end{syntax} - - Only for attributes of type |date|. Output of \cs{dbuse}\marg{date attr} - will be \meta{control sequence}\marg{date}. -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{before-code} - \begin{syntax} - before-code = <code> - \end{syntax} - - Set the \meta{code} that is executed \enbefore displaying the database. -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{after-code} - \begin{syntax} - after-code = <code> - \end{syntax} - - Set the \meta{code} that is executed \enafter displaying the database. -\end{option} - -\changes{1.2}{2022-01-08}{Add options}{\opt{record-before-code}, -\opt{record-after-code}} -\begin{option}[added=2022-01-05, rEXP]{record-before-code} - \begin{syntax} - record-before-code = <code> - \end{syntax} - - Set the \meta{code} that is executed \enbefore displaying a record. -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{record-after-code} - \begin{syntax} - record-after-code = <code> - \end{syntax} - - Set the \meta{code} that is executed \enafter displaying the record. -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{<attr>/before-code} - \begin{syntax} - <attr>/before-code = <code> - \end{syntax} - - Set the \meta{code} that is executed by \cs{dbuse} \enbefore displaying - certain attribute. -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{<attr>/after-code} - \begin{syntax} - <attr>/after-code = <code> - \end{syntax} - - Set the \meta{code} that is executed by \cs{dbuse} \enafter displaying - certain attribute. -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{<attr>/item-before-code} - \begin{syntax} - <attr>/item-before-code = <code> - \end{syntax} - - Only for attributes of type |clist|. Set the \meta{code} that is excuted - \enbefore displaying the item of the comma list. -\end{option} - -\begin{option}[added=2022-01-05, rEXP]{<attr>/item-after-code} - \begin{syntax} - <attr>/item-after-code = <code> - \end{syntax} - - Only for attributes of type |clist|. Set the \meta{code} that is excuted - \enafter displaying the item of the comma list. -\end{option} - -\subsection{Use \cs{dbNewReviewPoints} to Define Review Points} - -\begin{function}[added=2022-01-05]{\dbNewReviewPoints} - \begin{syntax} - \cs{dbNewReviewPoints} \marg{name} \marg{points} - \end{syntax} - - Define the new \meta{points} that is specially designed for reviewing - something. \meta{points} is a list of integers. Suppose you record the date - when you did not answer correctly and you plan to review every 2, 5 and 15 - days. The following code give what you want. -\end{function} - -\begin{verbatim} - \dbNewReviewPoints{review-point}{2, 5, 15} % define points - \begin{dbFilters} - \dbNewConditional{cond1}{date}{review-point|\Today} % define conditional - \dbCombineConditionals{filter1}{cond1} % define filter - \end{dbFilters} - \dbNewStyle{review-style}{ques}{filter=filter1} % define style -\end{verbatim} - -\subsection{Define Filters inside \env{dbFilters} Environment} - -\begin{environment}[added=2022-01-05]{dbFilters} - \begin{syntax} - |\begin{dbFilters}|\marg{database} \\ - ~~\meta{code} - |\end{dbFilters}| \\ - \end{syntax} - - Filters are defined inside \env{dbFilters} environment, inside which, - \cs{dbNewConditional} is defined to declare conditionals and - \cs{dbCombineConditionals} is defined to combine conditionals. Filters are - independent in different databases, which means the same name of filters is - allowed in different databases. -\end{environment} - -\begin{function}[added=2022-01-05, updated=2022-01-08]{\dbNewConditional, \dbNewConditional*} - \begin{syntax} - \cs{dbNewConditional} \marg{name} \marg{attr} \marg{cond spec} \\ - \cs{dbNewConditional}* \marg{name} \marg{attr} \marg{cond spec} \\[2pt] - \cs{dbNewConditional} \marg{name} \marg{int/fp attr} \marg{expr} \\ - \cs{dbNewConditional}* \marg{name} \marg{int/fp attr} \marg{expr} \\ - \cs{dbNewConditional} \marg{name} \marg{str/tl attr} \marg{regex expr} \\ - \cs{dbNewConditional}* \marg{name} \marg{str/tl attr} \marg{regex expr} \\ - \cs{dbNewConditional} \marg{name} \marg{clist attr} \marg{val list} \\ - \cs{dbNewConditional}* \marg{name} \marg{clist attr} \marg{val list} \\ - \cs{dbNewConditional} \marg{name} \marg{date attr} \marg{expr} - \cs{dbNewConditional}* \marg{name} \marg{date attr} \{\meta{review points}\orbar\meta{date}\} \\ - \end{syntax} - - Define the conditional named \meta{name} that binds to \meta{attr}. \cs{dbval} - is replaced with the real value of the attribute inside the \meta{cond spec}. -\end{function} - - \changes{1.3}{2022-01-10}{Update doc}{truncated division} - For attributes of type |int| and |fp|, \meta{expr} is passed to - \cs{int_compare:nTF} or \cs{fp_compare:nTF}. - \begin{note} - Division using |/| rounds to the closest integer. Use \cs{dbIntDivTruncate} to rounds - the result toward 0. - \end{note} - - For attribute of type |str| and |tl|, unstarred form matches any part while - starred form matches the whole part with the \meta{regex expr}. - -\begin{verbatim} - \dbNewConditional {cond1}{str-attr}{abc} % match abc, abcd, 1abc, =abc=, etc - \dbNewConditional*{cond2}{str-attr}{abc} % only match abc -\end{verbatim} - - For attributes of type |clist|, the conditional defined by unstarred form is - true if any item of \meta{val list} is in the comma list. While the - conditional defined by starred form is true only if every item of \meta{val - list} is in the comma list. As is showed below, for |cond1|, |a| is in - |{a, b, d}| so |cond1| is true. While |c| is not in |{a, b, d}| so |cond2| - is false. - -\begin{verbatim} - \dbNewConditional {cond1}{clist-attr}{a, b, c} % {a, b, d} -> true - \dbNewConditional*{cond2}{clist-attr}{a, b, c} % {a, b, d} -> false -\end{verbatim} - - \changes{1.3}{2022-01-08}{Update logic}{swap definition of starred and - unstarred conditionals of date} - For attributes of type |date|, unstarred form replace each date with a - integer representing for the days between \meta{date} and - \textit{1971/01/01}, and the result is passed to \cs{int_compare:nTF}. - Starred form defines the conditional with review points defined by - \cs{dbNewRdbNewReviewPoints} and \meta{date} is the date to be compared. - -\begin{function}[added=2022-01-05]{\dbCombineConditionals} - \begin{syntax} - \cs{dbCombineConditionals} \marg{name} \marg{cond combination} \oarg{info} - \end{syntax} - - Define the filter \meta{name}, which combine the conditionals and store the - extra \meta{info} into \cs{dbFilterInfo}. So you can write something as\\ - \verb=\dbCombineConditionals{filter}{(cond1 && cond2) || !cond3}=.\\ - Supported operators are \verb=&&, ||, !=. You can set the option \opt{filter} - to \meta{name} to apply the filter when you display the database. -\end{function} - -\subsection{Store Data with \env{dbitem} Environment} - -\begin{environment}[added=2022-01-05]{dbitem} - \begin{syntax} - |\begin{dbitem}|\marg{database}[ \\ - ~~\meta{attr1} = \meta{val1}, \\ - ~~\meta{attr2} = \meta{val2}, \\ - ~~\ldots{} \\ - ] \\ - ~~\meta{code} \\ - |\end{dbitem}| - \end{syntax} - - The data are stored with \env{dbitem} environment in two ways. Smaller data - can be stored in the option list and the bigger data can be stored by - \cs{dbsave}, which will suppress the value set by the option list. An - example code is showned below. -\end{environment} - -\begin{verbatim} - \begin{dbitem}[date=2022-01-01, info=test] - \dbsave{question}{This is a test question.} - \dbsave{answer} {This is a test answer.} - \end{dbitem} -\end{verbatim} - -\subsection{\cs{dbsave} and \cs{dbuse}} - -\changes{1.3}{2022-01-08}{Add macro}{\cs{dbsave*}} -\begin{function}[added=2022-01-05, updated=2022-01-08]{\dbsave, \dbsave*} - \begin{syntax} - \cs{dbsave} \marg{attr} \marg{data} \\ - \cs{dbsave}* \marg{attr} \marg{data} - \end{syntax} - - \cs{dbsave} save the \meta{data} to \meta{attr} of current record. - \cs{dbsave} can be used only inside the \env{dbitem} environment. - \meta{data} stored by \cs{dbsave*} is wrapped with \cs{exp_not:n} while - \meta{data} stored by \cs{dbsave} keeps the same. -\end{function} - -\changes{1.2}{2022-01-08}{Update macro}{make \cs{dbuse} fully-expandable} -\begin{function}[added=2022-01-05, updated=2022-01-08, EXP]{\dbuse} - \begin{syntax} - \cs{dbuse} \marg{attr} - \end{syntax} - - 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}[added=2022-01-05, EXP]{\dbIfEmptyT, \dbIfEmptyF, \dbIfEmptyTF} - \begin{syntax} - \cs{dbIfEmptyTF} \marg{true code} \marg{false code} \\ - \cs{dbIfEmptyT} \marg{true code} \\ - \cs{dbIfEmptyF} \marg{false code} - \end{syntax} - - Test if the database is empty. The example below shows how to avoid an empty - list environment. -\end{function} - -\begin{verbatim} - \dbNewStyle{style-cond1}{database-test}{ - before-code = {\dbIfEmptyF{\begin{enumerate}}}, - after-code = {\dbIfEmptyF{\end{enumerate}}}, - item-code = {\item \dbuse{attr-test}} - } -\end{verbatim} - -\changes{1.2}{2022-01-08}{Remove macros}{\cs{dbItemIfEmpty(TF)}, \cs{dbClistItemIfEmpty(TF)}} - -\subsection{Expression Functions} - -\changes{1.3}{2022-01-10}{Add macros}{expression function aliases} -\begin{function}[added=2022-01-10, EXP]{ - \dbIntAbs, \dbIntSign, \dbIntDivRound, \dbIntDivTruncate, \dbIntMax, - \dbIntMin, \dbIntMod, \dbFpSign, -} - \begin{syntax} - \cs{dbIntAbs} \Arg{intexpr} - \cs{dbIntSign} \Arg{intexpr} - \cs{dbIntDivRound} \Arg{intexpr_1} \marg{intexpr_2} - \cs{dbIntDivTruncate} \Arg{intexpr_1} \marg{intexpr_2} - \cs{dbIntMax} \Arg{intexpr_1} \marg{intexpr_2} - \cs{dbIntMin} \Arg{intexpr_1} \marg{intexpr_2} - \cs{dbIntMod} \Arg{intexpr_1} \marg{intexpr_2} - \cs{dbFpSign} \Arg{fpexpr} - \end{syntax} - \cs{dbIntAbs} is identical to \cs{int_abs:n} \\ - \cs{dbIntSign} is identical to \cs{int_sign:n} \\ - \cs{dbIntDivRound} is identical to \cs{int_div_round:nn} \\ - \cs{dbIntDivTruncate} is identical to \cs{int_div_truncate:nn} \\ - \cs{dbIntMax} is identical to \cs{int_max:nn} \\ - \cs{dbIntMin} is identical to \cs{int_min:nn} \\ - \cs{dbIntMod} is identical to \cs{int_mod:nn} \\ - \cs{dbFpSign} is identical to \cs{fp_sign:n} \\ - Detailed documentation see \pkg{interface3} \\ -\end{function} - -\subsection{Special Macros} - -Some special macros are defined to expand to different contents according to context. - -\changes{1.1}{2022-01-05}{Add macro}{ - \cs{dbarabic}, \cs{dbalph}, \cs{dbAlph}, \cs{dbroman}, - \cs{dbRoman} -} -\changes{1.1}{2022-01-06}{Fix bug}{\cs{dbIndex} not defined} -\begin{function}[added=2022-01-05, EXP]{ - \dbval, \dbDatabase, \dbFilterName, \dbFilterInfo, - \dbIndex, \dbarabic, \dbalph, \dbAlph, \dbroman, \dbRoman -} -\begin{tblr}{ll} - \cs{dbval} & Attribute value, only according in \cs{dbNewConditional}. \\ - \cs{dbDatabase} & Database name. \\ - \cs{dbFilterName} & Filter name. \\ - \cs{dbFilterInfo} & Filter information. \\ - \cs{dbIndex} & Record index, identical to \cs{dbuse}|{id}| \\ - \cs{dbarabic} & Show the counter of query set as digits. \\ - \cs{dbalph} & Show the counter of query set as lowercase letters. \\ - \cs{dbAlph} & Show the counter of query set as uppercase letters. \\ - \cs{dbroman} & Show the counter of query set as lowercase roman numerals. \\ - \cs{dbroman} & Show the counter of query set as uppercase roman numerals. \\ - \end{tblr} -\end{function} - -\section{Example of Flaw Sweeper Template} -\label{sec:example} - -\changes{1.1}{2022-01-07}{Update doc}{improve example} - -\begin{tcblisting}{enhanced jigsaw,lower separated=false, - leftlower=0pt,rightlower=0pt, - colframe=red!50!black,colback=yellow!10!white, - listing options={style=tcblatex,texcsstyle=*\color{red!70!black}}, - listing and comment, - pdf comment,freeze pdf, - compilable listing, - breakable, - run pdflatex -} -\documentclass{article} -\usepackage{amsmath, physics} -\usepackage{geometry} -\usepackage{dbshow} -\usepackage{tikz} -\usepackage{tcolorbox} -\tcbuselibrary{skins} -\usetikzlibrary{shadings} -\usepackage[hidelinks]{hyperref} - -\geometry{ - margin=2cm -} - -% #1 link node #2 target node #3 text to show -\NewDocumentCommand \linktarget { m m m } {% - \hyperlink{#1}{#3}% - \raisebox{1em}{\hypertarget{#2}{}}% -} - -% question box -\tcbset{ - base/.style={ - empty, - frame engine=path, - colframe=yellow!10, - coltitle=red!70, - fonttitle=\bfseries\sffamily, - sharp corners, - left=4pt, - right=4pt, - drop fuzzy shadow, - drop fuzzy shadow, - borderline west={3pt}{-3pt}{red!80}, - } -} - -\newtcolorbox{mybox}[1]{% - base, title = {#1} -} - -\dbNewReviewPoints{review}{1, 3, 7, 15, 30, 60} - -\dbNewDatabase{ques-book}{ - ques = tl, - answer = tl, - count = int|1, - labels = clist, - date = date, -} - -\begin{dbFilters}{ques-book} - \dbNewConditional{hard}{labels}{hard} - \dbNewConditional{bad}{count}{\dbval > 1} - \dbNewConditional*{review}{date}{review|2022/01/07} - \dbNewConditional{after}{date}{\dbval > 2022/01/02} -\end{dbFilters} - -% show all questions with hyperlink to answers -\dbNewStyle{ques}{ques-book}{ - before-code = {\section{Questions}}, - item-code = { - \begin{mybox}{% - \linktarget{answer_\dbIndex}{ques_\dbIndex}{% - Question \dbarabic% - \hspace{2em}\dbuse{date}% - \hspace{2em}\dbuse{labels}% - \hfill\dbuse{count}% - }% - } - \dbuse{ques}% - \end{mybox} - }, - labels/sep = /, -} - -% show all questions and answers with hyperlink to questions -\dbNewStyle{answer}{ques-book}{ - before-code = {\section{Questions and Answers}}, - item-code = { - \begin{mybox}{% - \linktarget{ques_\dbIndex}{answer_\dbIndex}{% - Question \dbarabic% - \hspace{2em}\dbuse{date}% - \hspace{2em}\dbuse{labels}% - \hfill\dbuse{count}% - }% - } - \dbuse{ques}\tcbsubtitle{Answer}\dbuse{answer}% - \end{mybox} - }, - labels/sep = /, -} - -% show all hard questions with hyperlink to answers -\dbNewStyle{hard}{ques-book}{ - before-code = {\section{Hard Questions}}, - item-code = { - \begin{mybox}{% - \hyperlink{answer_\dbIndex}{% - Question \dbarabic% - \hspace{2em}\dbuse{date}% - \hspace{2em}\dbuse{labels}% - \hfill\dbuse{count}% - }% - } - \dbuse{ques}% - \end{mybox} - }, - raw-filter = hard, - labels/sep = /, -} - -% show all hard questions that have been answered incorrectly for more than -% one time with hyperlink to answers -\dbNewStyle[hard]{bad}{ques-book}{ - before-code = {\section{Bad Questions}}, - raw-filter = {bad && hard}, -} -% show all questions that plan to be reviewed on 2022/01/07 with hyperlink to -% answers -\dbNewStyle[hard]{review}{ques-book}{ - before-code = {\section{Questions to be Reviewed}}, - raw-filter = {review}, -} -% show all questions that is record after 2022/01/02 with hyperlink to answers -\dbNewStyle[hard]{after}{ques-book}{ - before-code = {\section{Questions after 2022/01/02}}, - raw-filter = {after}, -} - -\AtEndDocument{ - \dbshow{review}{ques-book} - \dbshow{hard}{ques-book} - \dbshow{bad}{ques-book} - \dbshow{after}{ques-book} - \dbshow{ques}{ques-book} - \dbshow{answer}{ques-book} -} - -\begin{document} - -\begin{dbitem}{ques-book}[ - date=2022/01/01, - labels={math, equation, easy}, - count=2 - ] - \dbsave{ques}{% - Solve the linear equation: $x + 16 = 31$. - } - \dbsave{answer}{% - $x = 31 - 16 = 15$ - } -\end{dbitem} - -\begin{dbitem}{ques-book}[ - date=2022/01/01, - labels={math, equation, hard}, - count=3 - ] - \dbsave{ques}{% - Solve the linear equation: $2y = 16$. - } - \dbsave{answer}{% - $y = 16 / 2 = 8$ - } -\end{dbitem} - -\begin{dbitem}{ques-book}[ - date=2022/01/04, - labels={math, integral, hard}, - count=1 - ] - \dbsave{ques}{% - Find the indefinite integral: $\int 2x \dd x$. - } - \dbsave{answer}{% - $\int 2x \dd x = x^2$ - } -\end{dbitem} - -\end{document} -\end{tcblisting} - -\end{documentation} -\end{document} |