Debian Codegraph @

texmf-dist/source/latex/query-astro/query-astro.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2026 Valentin Dao
4 %
5 % This file may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either
7 % version 1.3c of this license or (at your option) any later
8 % version. The latest version of this license is in:
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % and version 1.3c or later is part of all distributions of
13 % LaTeX version 2008-05-04 or later.
14 %
15 % This work has the LPPL maintenance status 'maintained'
16 % and the current maintainer is Valentin Dao ([email protected]).
17 %
18 % This work consists of the files contained in the file 'MANIFEST.md'
19 %
20 % The repository of this work can be found at:
21 %
22 % https://github.com/TeXackers/query-astro
23 %
24 %<*driver>
25 % \fi
26 % \iffalse
27 \documentclass[11pt, a4paper]{l3doc}
28
29 \usepackage{fontspec}
30
31 \setmainfont{ChronicleTextG3}[
32 Extension = .otf,
33 Renderer = HarfBuzz,
34 UprightFont = *-Roman-Pro,
35 UprightFeatures = { Kerning = On },
36 ItalicFont = *-Italic-Pro,
37 BoldFont = *-Bold-Pro,
38 BoldItalicFont = *-BoldIta-Pro,
39 ]
40
41 \setsansfont{Whitney}[
42 Extension = .otf,
43 UprightFont = *-Medium,
44 ItalicFont = *-MediumItalic,
45 BoldFont = *-Bold,
46 BoldItalicFont = *-BoldItalic,
47 UprightFeatures =
48 {
49 StylisticSet = 1,
50 StylisticSet = 10,
51 StylisticSet = 11,
52 },
53 BoldFeatures =
54 {
55 StylisticSet = 1,
56 StylisticSet = 10,
57 StylisticSet = 11,
58 },
59 ItalicFeatures =
60 {
61 StylisticSet = 1,
62 StylisticSet = 10,
63 StylisticSet = 11,
64 StylisticSet = 8,
65 StylisticSet = 9
66 }
67 ]
68
69 \setmonofont{MonaspaceNeon}[
70 Extension = .otf,
71 Renderer = HarfBuzz,
72 Scale = 0.8,
73 UprightFont = *-Regular,
74 UprightFeatures = { Kerning = On },
75 ItalicFont = *-Italic,
76 BoldFont = *-Bold,
77 BoldItalicFont = *-BoldItalic,
78 ]
79
80 \usepackage{microtype}
81
82 \usepackage{fancyhdr}
83 \fancyhf{}
84 \fancyfoot[C]{\small\sffamily\itshape---\space\thepage\space\kern0.4mm\/---}
85 \renewcommand{\headrulewidth}{0pt}
86 \pagestyle{fancy}
87
88 \usepackage{query-astro}
89
90 \usepackage[silence]{codedescribe}
91 \usepackage{hologo}
92
93 \usepackage[svgnames]{xcolor}
94
95 \definecolor{RoyalBlue}{RGB}{0, 35, 102}
96 \definecolor{RoyalRed}{RGB}{157, 16, 45}
97 \definecolor{RoyalGreen}{HTML}{48845F}
98 \definecolor{urlcolour}{HTML}{B42F5E}
99
100 \definecolor{packagecolour}{HTML}{B86B00}
101 \definecolor{keycolour}{HTML}{004766}
102 \definecolor{macrocolour}{HTML}{047658}
103 \definecolor{macrocolour2}{HTML}{630476}
104
105 \defobjectfmt{macro}{code}{color=macrocolour}
106 \defobjectfmt{pkg}{pkg}{color=packagecolour, font=\sffamily}
107
108 \newcodekey{fits}{
109 ruleht = 0,
110 texcsstyle = \bfseries\color{RoyalBlue},
111 texcs =
112 [2]{
113 loadheader,
114 showheader,
115 headerkey,
116 setheaderkey,
117 gsetheaderkey,
118 },
119 texcs =
120 [3]{
121 flameHalpha,
122 exptime,
123 observer,
124 },
125 texcsstyle = [2]{\color{macrocolour}},
126 texcsstyle = [3]{\color{macrocolour2}},
127 codeprefix = {},
128 resultprefix = {}
129 }
130
131 \lstset{
132 gobble=2,
133 }
134
135 \directlua{
136 target_list = {}
137 local path = '../../build.lua'
138 dofile(path)
139 token.set_macro('pkgversion', uploadconfig.version)
140 token.set_macro('pkgname', uploadconfig.pkg)
141 token.set_macro('pkgauthor', uploadconfig.author)
142 token.set_macro('pkgemail', uploadconfig.email)
143 texio.write_nl(uploadconfig.author)
144 }
145
146 \usepackage{titlesec}
147 \titleformat*{\section}{\sffamily\LARGE\bfseries}
148 \titleformat*{\subsection}{\sffamily\Large\bfseries}
149
150 \usepackage{changelog}
151 \usepackage{enumitem}
152 \renewenvironment{changelogitemize}
153 {\begin{itemize}[label=\raisebox{0.5ex}{$\scriptscriptstyle\blacktriangleright$}]}
154 {\end{itemize}}
155
156 \setlength{\parindent}{0pt}
157
158 \usepackage{polyglossia}
159 \setmainlanguage{english}
160
161 \usepackage{siunitx}
162 \sisetup{
163 propagate-math-font = true,
164 retain-explicit-plus = true,
165 uncertainty-mode = separate,
166 round-mode = places,
167 round-precision = 2,
168 }
169
170 \usepackage[
171 backend = biber,
172 casechanger = expl3,
173 sorting = none,
174 url = true,
175 doi = true,
176 maxcitenames = 1
177 ]{biblatex}
178 \addbibresource{query-astro.bib}
179
180 \usepackage[perpage]{footmisc}
181
182 \usepackage{hyperref}
183 \hypersetup{
184 pdfauthor = {Valentin Dao},
185 pdftitle = {The query-astro package},
186 pdfcreator = {LuaLaTeX with hyperref package},
187 colorlinks = true,
188 urlcolor = urlcolour,
189 linkcolor = RoyalBlue,
190 citecolor = RoyalGreen,
191 }
192
193 \title{The \textsf{\pkgname} package\medbreak{\Large\pkgversion}}
194 \author{\pkgauthor\footnote{E-mail: \href{mailto:[email protected]}{\ttfamily\pkgemail}}}
195 \date{\today}
196
197 \begin{document}
198 \DocInput{query-astro.dtx}
199 \end{document}
200 %</driver>
201 % \fi
202 %
203 % \begin{documentation}
204 %
205 % \maketitle
206 %
207 % The \tsobj[pkg]{\pkgname} package provides a minimalist interface to mimic Python's \href{https://astroquery.readthedocs.io/en/latest/}{Astroquery} library, using cURL to send ADQL queries to the TAP services of major astronomical databases. It therefore requires \textbf{shell escape} to be enabled. Note that all queries are performed \emph{synchronously}: a resource-intensive query (e.g.\ \texttt{SELECT TOP 100 *} against the Gaia catalogue) may significantly slow down compilation.\footnotemark[1] Simple queries are thus strongly recommended. For now, \tsobj[pkg]{\pkgname} supports two databases (Simbad and Gaia) which should cover most use cases; future versions will allow users to register custom TAP service URLs. As of now, only raw ADQL queries are supported. No higher-level interface is provided, though this is planned for future versions. The package is still in active development, so some rough edges are to be expected. Finally, users are reminded that properly crediting the queried databases remains their own responsibility; this package is merely a convenience wrapper for \LaTeX.
208 % \footnotetext[1]{Asynchronous queries are not currently supported, as I am unaware of a straightforward way to implement async TAP services in \TeX\dots if it is even possible at all.}
209 %
210 % \section{Functioning of the package}
211 %
212 % The package essentially works in three steps:
213 %
214 % \begin{enumerate}
215 % \item The ADQL query is written in a auxiliary file named \texttt{query.ADQL}.
216 % \item A cURL configuration file named \texttt{curl.cfg} is generated.
217 % \item The query is executed by calling cURL with the generated configuration file. The result is then stored in a auxiliary file named \texttt{query-result.txt}.
218 % \end{enumerate}
219 %
220 % Every time you run a query, these files get overwritten.
221 %
222 % \section{Package macro}
223 %
224 % \begin{codedescribe}[macro]{\ADQLquery}
225 % \begin{codesyntax}
226 % \tsobj[macro]{\ADQLquery}\tsargs[marg]{macro}\tsargs[marg]{ADQL query}\tsargs[oarg]{database}
227 % \end{codesyntax}
228 % This macro executes the ADQL request and stores the result in the provided \tsargs[marg]{macro}. The nature of this macro depends on the number of queried keys with \texttt{SELECT}. If only one key was submitted, then the macro will be defined without arguments. If a list of keys was provided, then the individual results may be retrieved by specifying their index as an argument. In both cases, the macro will be expandable. Although \tsobj[macro]{\ADQLquery} can support storing multiple columns, it \emph{does not} support storing multiple rows. Hence, any query that goes along the line of \texttt{SELECT TOP...} will, in theory, work, but only the first row from the text file will be inspected. If you don't mind this limitation, you can safely ignore this warning. The optional argument \tsargs[oarg]{database} specifies the database to query. For now, here is the list of supported databases:
229 % \begin{describelist*}{option}
230 % \describe{simbad}{The Simbad astronomical database.~\cite{simbad}}
231 % \describe{gaia}{The Gaia astronomical database.~\cite{GaiaCollaboration2016}~\cite{GaiaDR3_2023}}
232 % \end{describelist*}
233 % If it isn't specified, Simbad will always be used. Here are a few examples of use:
234 % \end{codedescribe}
235 %
236 % \begin{codestore}[simbad-mag]
237 % \ADQLquery\SimbadVMag{
238 % SELECT V
239 % FROM allfluxes
240 % JOIN ident ON allfluxes.oidref = ident.oidref
241 % WHERE ident.id = 'Betelgeuse'
242 % }
243 % The V-band magnitude of Betelgeuse is \SimbadVMag.
244 % \end{codestore}
245 %
246 % \tsdemo*[fits]{simbad-mag}
247 %
248 % \begin{codestore}[simbad-coords]
249 % \ADQLquery\SimbadCoords{
250 % SELECT ROUND(ra, 5), ROUND(dec, 5)
251 % FROM basic
252 % WHERE main_id = 'M31'
253 % }
254 % Right ascension: \SimbadCoords{1}\par
255 % Declination: \SimbadCoords{2}
256 % \end{codestore}
257 %
258 % \tsdemo*[fits]{simbad-coords}
259 %
260 % \begin{codestore}[gaia-parallax]
261 % \DeclareSIUnit\milliarcsecond{mas}
262 % \ADQLquery\SiriusParallax{
263 % SELECT ROUND(parallax, 5), ROUND(parallax_error, 5)
264 % FROM gaiadr3.gaia_source_lite
265 % WHERE source_id = 2947050466531873024
266 % }[gaia]
267 % The parallax of Sirius is $\SiriusParallax{1} \pm \SiriusParallax{2} \unit{\milliarcsecond}$.
268 % \end{codestore}
269 %
270 % \tsdemo*[fits]{gaia-parallax}
271 %
272 % \begin{changelog}[sectioncmd=\section*]
273 % \shortversion{v=0.1.0, date=20-04-2026, changes=Initial version.}
274 % \end{changelog}
275 %
276 % \end{documentation}
277 %
278 % \printbibliography
279 %
280 % \newpage
281 %
282 % \section{Implementation}
283 %
284 % \begin{implementation}
285 %
286 % \begin{macrocode}
287 %<*package>
288 %<@@=query_astro>
289 \NeedsTeXFormat{LaTeX2e}
290
291 \def\queryastro@module{query-astro}
292 \def\queryastro@version{v0.1.0}
293 \def\queryastro@date{2026-04-20}
294 \def\queryastro@description{Querying astronomical databases with ADQL in LaTeX}
295
296 \ProvidesExplPackage
297 \queryastro@module
298 \queryastro@date
299 \queryastro@version
300 \queryastro@description
301
302 \sys_if_shell_unrestricted:F { \PackageError{query-astro}{query-astro~requires~shell~escape} }
303
304 \cs_generate_variant:Nn \seq_gset_split:NnV { cnV }
305
306 \iow_new:N \g_@@_ADQL_query_iow
307 \iow_new:N \g_@@_curl_config_iow
308 \ior_new:N \g_@@_ADQL_result_ior
309
310 \tl_new:N \l_@@_TAP_url_tl
311 \tl_const:Nn \c_@@_simbad_TAP_url_tl { https://simbad.u-strasbg.fr/simbad/sim-tap/sync }
312 \tl_const:Nn \c_@@_gaia_TAP_url_tl { https://gea.esac.esa.int/tap-server/tap/sync }
313
314 \cs_new_protected:Npn \@@_write_curl_configuration:n #1
315 {
316 \iow_open:Nn \g_@@_curl_config_iow { curl.cfg }
317 \iow_now:Ne \g_@@_curl_config_iow { #1 }
318 \iow_close:N \g_@@_curl_config_iow
319 }
320
321 \cs_new_protected:Npn \@@_write_ADQL_query:n #1
322 {
323 \iow_open:Nn \g_@@_ADQL_query_iow { query.ADQL }
324 \iow_now:Ne \g_@@_ADQL_query_iow { #1 }
325 \iow_close:N \g_@@_ADQL_query_iow
326 }
327
328 \cs_new_protected:Npn \@@_execute_ADQL_query:n #1
329 {
330 \@@_write_ADQL_query:n { #1 }
331 \@@_write_curl_configuration:n
332 {
333 data-urlencode~=~"[email protected]"^^J
334 data~=~"REQUEST=doQuery"^^J
335 data~=~"LANG=ADQL"^^J
336 data~=~"FORMAT=csv"^^J
337 url~=~"\l_@@_TAP_url_tl"^^J
338 output~=~"query-result.txt"^^J
339 }
340 \sys_shell_now:n {curl~--config~curl.cfg}
341 }
342
343 \cs_new_protected:Npn \@@_retrieve_ADQL_result:n #1
344 {
345 \ior_open:Nn \g_@@_ADQL_result_ior { query-result.txt }
346 \ior_get:NN \g_@@_ADQL_result_ior \l_tmpa_tl % ignore header
347 \ior_get:NN \g_@@_ADQL_result_ior \l_tmpb_tl
348 \seq_new:c { g_@@_ADQL_#1_result_seq }
349 \seq_gset_split:cnV { g_@@_ADQL_#1_result_seq } { , } \l_tmpb_tl
350 \ior_close:N \g_@@_ADQL_result_ior
351 \int_compare:nNnTF { \seq_count:c { g_@@_ADQL_#1_result_seq } } > { 1 }
352 { \cs_new:cpn { #1 } ##1 { \seq_item:cn { g_@@_ADQL_#1_result_seq } { ##1 } } }
353 { \cs_new:cpn { #1 } { \seq_item:cn { g_@@_ADQL_#1_result_seq } { 1 } } }
354 }
355
356 \NewDocumentCommand\ADQLquery{ m m O{simbad} }
357 {
358 \str_case:nnF {#3}
359 {
360 {simbad} { \tl_set_eq:NN \l_@@_TAP_url_tl \c_@@_simbad_TAP_url_tl }
361 {gaia} { \tl_set_eq:NN \l_@@_TAP_url_tl \c_@@_gaia_TAP_url_tl }
362 }
363 { \PackageError{query-astro}{Unknown~database:~'#3'}{} }
364 \@@_execute_ADQL_query:n {#2}
365 \exp_args:Ne \@@_retrieve_ADQL_result:n { \cs_to_str:N #1 }
366 }
367 %</package>
368 % \end{macrocode}
369 % \end{implementation}