% Copyright (C) 2026 Landon Fox
%
% This work may be distributed and/or modified under the conditions of the
% LaTeX Project Public License, either version 1.3c of this license or (at your
% option) any later version. The latest version of this license is in
%   https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX version
% 2008 or later.
%
% This work has the LPPL maintenance status `maintained'.
% The Current Maintainer of this work is Landon Fox.
%
% This work consists of the files beltmap.sty, tikzlibrarybeltmap.code.tex,
% beltmap.lua, beltmap-net.lua, beltmap_export.py, beltmap-doc.tex, and the
% files in examples/.

% beltmap.sty: schematic pictures of Factorio belt layouts in LuaLaTeX.
%
% Front ends, all drawn by the glyphs and themes of tikzlibrarybeltmap.code.tex:
%   \beltlayout[keys]{file}         Factorio-SAT tiles (.json), search records (.jsonl),
%                                   or a file holding a blueprint string or book
%   \beltblueprint[keys]{string}    a blueprint string written into the document
%   \begin{beltgrid}[keys] ... \end{beltgrid}      a layout typed as a character grid
%   \beltglyph[keys]{kind}          one glyph inline, for running text and captions
%   \usetikzlibrary{beltmap}        the glyphs by hand, in any tikzpicture
% Reading, tracing and the TikZ code are done in beltmap.lua.  See beltmap-doc.pdf.
\NeedsTeXFormat{LaTeX2e}[2024-06-01]
\ProvidesExplPackage{beltmap}{2026-11-19}{0.1}{Schematic pictures of Factorio belt layouts}

\sys_if_engine_luatex:F
	{
		\msg_new:nnn { beltmap } { engine } { beltmap~needs~LuaLaTeX:~it~reads~layouts~and~blueprint~strings~in~Lua. }
		\msg_critical:nn { beltmap } { engine }
	}

% The libraries are read with ordinary catcodes: under expl3 syntax their spaces vanish.
\ExplSyntaxOff
\RequirePackage{tikz}
\usetikzlibrary{beltmap}
\ExplSyntaxOn
\lua_now:n { beltmap = require('beltmap') }

\tl_new:N \l__beltmap_tier_tl
\tl_new:N \l__beltmap_trim_tl
\tl_new:N \l__beltmap_color_tl
\tl_new:N \l__beltmap_flow_tl
\tl_new:N \l__beltmap_mix_tl
\tl_new:N \beltmapverdict
\tl_new:N \beltmapstring
\tl_new:N \l__beltmap_blueprint_tl
\tl_new:N \l__beltmap_bplabel_tl
\tl_new:N \l__beltmap_bpfile_tl
\tl_new:N \l__beltmap_bpref_tl
\tl_new:N \l__beltmap_grid_tl
\tl_new:N \l__beltmap_ends_tl
\tl_new:N \l__beltmap_heads_tl
\tl_new:N \l__beltmap_lanes_tl
\tl_new:N \l__beltmap_labels_tl
\tl_new:N \l__beltmap_openends_tl
\tl_new:N \l__beltmap_factorio_tl
\tl_new:N \l__beltmap_auto_alt_tl
\tl_new:N \l__beltmap_altkey_tl
\tl_new:N \l__beltmap_mixlanes_tl
\tl_new:N \l__beltmap_focus_tl
\tl_new:N \l__beltmap_step_tl
\tl_new:N \l__beltmap_palette_tl
\tl_new:N \l__beltmap_throughput_tl
\tl_new:N \l__beltmap_numbers_tl
\tl_new:N \l__beltmap_compare_tl
\tl_new:N \l__beltmap_view_tl
\tl_new:N \l__beltmap_expect_tl
\tl_new:N \l__beltmap_frames_tl
\tl_new:N \l__beltmap_gpath_tl
\tl_new:N \l__beltmap_bookfile_tl
\tl_new:N \l__beltmap_bookstring_tl
\tl_new:N \g__beltmap_booklabel_tl
\bool_new:N \g__beltmap_book_bool
\int_new:N \l__beltmap_columns_int
\tl_new:N \beltmaplanes
\tl_new:N \beltmapthroughput
\tl_new:N \beltmapcaption

% A key taking true or false, stored as text for beltmap.lua to read.
\cs_new_protected:Npn \__beltmap_bool_key:n #1
	{
		\keys_define:nn { beltmap }
			{
				#1 .choices:nn = { true , false } { \tl_set_eq:cN { l__beltmap_#1_tl } \l_keys_choice_tl } ,
				#1 .default:n = true ,
			}
	}
\clist_map_function:nN { ends , heads , lanes , labels , openends , throughput , numbers , dimensions } \__beltmap_bool_key:n
% grid: true (normal), false (none), faint, or strong; grid major=n, rulers=n, dimensions.
\keys_define:nn { beltmap }
	{
		grid .choices:nn = { true , false , none , faint , normal , strong } { \tl_set_eq:NN \l__beltmap_grid_tl \l_keys_choice_tl } ,
		grid .default:n = true ,
		grid~major .tl_set:N = \l__beltmap_gridmajor_tl ,
		rulers .tl_set:N = \l__beltmap_rulers_tl ,
		rulers .default:n = 1 ,
	}

\keys_define:nn { beltmap }
	{
		theme .tl_set:N = \l__beltmap_theme_tl ,
		theme .initial:n = schematic ,
		tile .tl_set:N = \l__beltmap_tile_tl ,
		tile .initial:n = 4.4mm ,
		gap .tl_set:N = \l__beltmap_gap_tl ,
		tier .choices:nn = { yellow , red , blue , turbo } { \tl_set_eq:NN \l__beltmap_tier_tl \l_keys_choice_tl } ,
		tier / none .code:n = { \tl_clear:N \l__beltmap_tier_tl } ,
		trim .choices:nn = { true , false , auto } { \tl_set_eq:NN \l__beltmap_trim_tl \l_keys_choice_tl } ,
		trim .default:n = true ,
		trim .initial:n = auto ,
		color .choices:nn = { belt , tier } { \tl_set_eq:NN \l__beltmap_color_tl \l_keys_choice_tl } ,
		color .initial:n = belt ,
		mix .choices:nn = { blend , bands , none } { \tl_set_eq:NN \l__beltmap_mix_tl \l_keys_choice_tl } ,
		mix .default:n = blend ,
		mix .initial:n = none ,
		mix~lanes .choices:nn = { true , false } { \tl_set_eq:NN \l__beltmap_mixlanes_tl \l_keys_choice_tl } ,
		mix~lanes .default:n = true ,
		focus .tl_set:N = \l__beltmap_focus_tl ,
		focus / none .code:n = { \tl_clear:N \l__beltmap_focus_tl } ,
		step .tl_set:N = \l__beltmap_step_tl ,
		palette .choices:nn = { wheel , okabe-ito , lightness , gray } { \tl_set_eq:NN \l__beltmap_palette_tl \l_keys_choice_tl } ,
		compare .tl_set:N = \l__beltmap_compare_tl ,
		view .choices:nn = { graph } { \tl_set_eq:NN \l__beltmap_view_tl \l_keys_choice_tl } ,
		view / layout .code:n = { \tl_clear:N \l__beltmap_view_tl } ,
		expect .tl_set:N = \l__beltmap_expect_tl ,
		columns .int_set:N = \l__beltmap_columns_int ,
		columns .initial:n = 3 ,
		limit .tl_set:N = \l__beltmap_limit_tl ,
		blueprint .choices:nn = { file , attach } { \tl_set_eq:NN \l__beltmap_blueprint_tl \l_keys_choice_tl } ,
		blueprint / none .code:n = { \tl_clear:N \l__beltmap_blueprint_tl } ,
		blueprint .default:n = attach ,
		blueprint~label .tl_set:N = \l__beltmap_bplabel_tl ,
		flow .choices:nn = { right , up , left , down } { \tl_set_eq:NN \l__beltmap_flow_tl \l_keys_choice_tl } ,
		flow / asis .code:n = { \tl_clear:N \l__beltmap_flow_tl } ,
		inputs .tl_set:N = \l__beltmap_inputs_tl ,
		outputs .tl_set:N = \l__beltmap_outputs_tl ,
		index .tl_set:N = \l__beltmap_index_tl ,
		label .tl_set:N = \l__beltmap_label_tl ,
		record .tl_set:N = \l__beltmap_record_tl ,
		pick .tl_set:N = \l__beltmap_pick_tl ,
		factorio .choices:nn = { 1.1 , 2.0 } { \tl_set_eq:NN \l__beltmap_factorio_tl \l_keys_choice_tl } ,
		alt .tl_set:N = \l__beltmap_alt_tl ,
		annotate .tl_set:N = \l__beltmap_annotate_tl ,
		tikz .tl_set:N = \l__beltmap_tikz_tl ,
	}
\ProcessKeyOptions [ beltmap ]

\NewDocumentCommand \beltmapset { m } { \keys_set:nn { beltmap } {#1} }

% The picture: #1 is the Lua call that reads the layout.  The alternative text goes to
% LaTeX's tagging code when the document is tagged (\DocumentMetadata with tagging=on),
% which defines the TikZ key alt; otherwise the key is left out.
\cs_new_protected:Npn \__beltmap_picture:n #1
	{
		\lua_now:e {#1}
		\tl_if_empty:NT \l__beltmap_alt_tl { \tl_set_eq:NN \l__beltmap_alt_tl \l__beltmap_auto_alt_tl }
		\cs_if_exist:cTF { pgfk@/tikz/alt/.@cmd }
			{ \tl_set:Ne \l__beltmap_altkey_tl { alt = { \exp_not:V \l__beltmap_alt_tl } , } }
			{ \tl_clear:N \l__beltmap_altkey_tl }
		\use:e
			{
				\exp_not:N \begin{tikzpicture}
					[
						bm~tile = \l__beltmap_tile_tl ,
						bm~theme = \l__beltmap_theme_tl ,
						\exp_not:V \l__beltmap_altkey_tl
						\exp_not:V \l__beltmap_tikz_tl
					]
			}
		\lua_now:n { beltmap.emit() }
		\l__beltmap_annotate_tl
		\end{tikzpicture}
		\str_if_eq:VnT \l__beltmap_blueprint_tl { attach } { \__beltmap_attach:NN \beltmapstring \l__beltmap_bpfile_tl }
	}

% blueprint=attach: the blueprint string as a text file inside the PDF, listed in the
% viewer's attachments.  With \DocumentMetadata the kernel's pdfmanagement embeds it, with
% an /AF entry as PDF 2.0 asks; without, the embedfile package embeds the file written beside
% the PDF.
\IfPDFManagementActiveTF
	{
		\cs_generate_variant:Nn \pdffile_embed_stream:nnN { VV }
		\cs_new_protected:Npn \__beltmap_attach:NN #1#2
			{
				\tl_if_empty:NF #2
					{
						\group_begin:
							\pdfdict_put:nnn { l_pdffile/Filespec } { AFRelationship } { /Supplement }
							\pdf_string_from_unicode:nnN { utf16/string } { Factorio~blueprint~string } \l_tmpa_str
							\pdfdict_put:nne { l_pdffile/Filespec } { Desc } { \l_tmpa_str }
							\pdffile_embed_stream:VVN #1 #2 \l__beltmap_bpref_tl
							\pdfmanagement_add:nne { Catalog / Names } { EmbeddedFiles } { \l__beltmap_bpref_tl }
							\pdfmanagement_add:nne { Catalog } { AF } { \l__beltmap_bpref_tl }
						\group_end:
					}
			}
	}
	{
		\RequirePackage{embedfile}
		\cs_new_protected:Npn \__beltmap_attach:NN #1#2
			{
				\tl_if_empty:NF #2
					{ \use:e { \exp_not:N \embedfile [ desc = { Factorio~blueprint~string } , mimetype = text/plain ] { #2 } } }
			}
	}

% The share matrix of the last picture: rows inputs, columns outputs, exact fractions.
\NewDocumentCommand \beltmapmatrix { } { \lua_now:n { beltmap.print_matrix() } }

% \beltmapbook[label]: at the end of the document, every blueprint written with blueprint=file
% or attach goes into one blueprint book, written to <jobname>-book.txt and attached.
\NewDocumentCommand \beltmapbook { O{beltmap} }
	{
		\bool_gset_true:N \g__beltmap_book_bool
		\tl_gset:Nn \g__beltmap_booklabel_tl {#1}
	}
\AtEndDocument
	{
		\bool_if:NT \g__beltmap_book_bool
			{
				\lua_now:e { beltmap.book('\lua_escape:e { \g__beltmap_booklabel_tl }') }
				\__beltmap_attach:NN \l__beltmap_bookstring_tl \l__beltmap_bookfile_tl
			}
	}

% \beltanimation[keys]{file}: one picture per step of the flow, from empty belts to the steady
% state, for beltmap_export.py --gif (or the animate package).
\NewDocumentCommand \beltanimation { O{} m }
	{
		\group_begin:
			\keys_set:nn { beltmap } {#1}
			\tl_if_empty:NT \l__beltmap_mix_tl { \tl_set:Nn \l__beltmap_mix_tl { blend } }
			\str_if_eq:VnT \l__beltmap_mix_tl { none } { \tl_set:Nn \l__beltmap_mix_tl { blend } }
			\lua_now:e { beltmap.count_frames('\lua_escape:e {#2}') }
			\int_step_inline:nnn { 0 } { \l__beltmap_frames_tl - 1 }
				{
					\tl_set:Nn \l__beltmap_step_tl {##1}
					\__beltmap_picture:n { beltmap.from_file('\lua_escape:e {#2}') }
					% a space between frames, where a line may break
					\c_space_tl
				}
		\group_end:
	}

% \beltgallery[keys]{file.jsonl}: every record with status "sat", columns= per row, each with
% its name, size and area and \beltmapcaption; pick= keeps one family, limit= the first n.
\NewDocumentCommand \beltgallery { O{} m }
	{
		\group_begin:
			\keys_set:nn { beltmap } {#1}
			\tl_set:Nn \l__beltmap_gpath_tl {#2}
			\par \noindent
			\lua_now:e { beltmap.gallery('\lua_escape:e {#2}') }
		\group_end:
	}
\cs_new_protected:Npn \BeltmapGalleryCell #1#2
	{
		\begin{minipage}[t]
			{ \dim_eval:n { ( \linewidth - 1em * ( \l__beltmap_columns_int - 1 ) ) / \l__beltmap_columns_int } }
			\centering
			\group_begin:
				\tl_set:Nn \l__beltmap_record_tl {#1}
				\tl_clear:N \l__beltmap_alt_tl
				\__beltmap_picture:n { beltmap.from_file('\lua_escape:e { \l__beltmap_gpath_tl }') }
			\group_end:
			\par \smallskip
			{ \scriptsize \sffamily #2 \par \beltmapcaption \par }
		\end{minipage}
	}

% The blueprint string of the last picture, typeset in a box #1 wide (\linewidth when
% left out) with a possible break after every character.
\NewDocumentCommand \beltmapprintstring { O{\linewidth} }
	{
		\parbox{#1}{ \raggedright \ttfamily \scriptsize \lua_now:n { beltmap.print_string() } }
	}

\NewDocumentCommand \beltlayout { O{} m }
	{
		\group_begin:
			\keys_set:nn { beltmap } {#1}
			\__beltmap_picture:n { beltmap.from_file('\lua_escape:e {#2}') }
		\group_end:
	}

\NewDocumentCommand \beltblueprint { O{} +m }
	{
		\group_begin:
			\keys_set:nn { beltmap } {#1}
			\__beltmap_picture:n { beltmap.from_string('\lua_escape:e { \tl_to_str:n {#2} }') }
		\group_end:
	}

% The body is read as text: cells separated by spaces, rows by \\ (see beltmap.lua).
\NewDocumentEnvironment { beltgrid } { O{} +b }
	{
		\group_begin:
			\keys_set:nn { beltmap } {#1}
			\__beltmap_picture:n { beltmap.from_grid('\lua_escape:e { \tl_to_str:n {#2} }') }
		\group_end:
	}
	{ }

\NewDocumentCommand \beltglyph { O{} m }
	{
		\group_begin:
			\keys_set:nn { beltmap } { grid = false , ends = false , labels = false , openends = false , blueprint = none , tile = 1.15em , #1 }
			\tl_put_left:Nn \l__beltmap_tikz_tl { baseline = { ([yshift=-0.55ex]current~bounding~box.center) } , }
			\__beltmap_picture:n { beltmap.from_glyph('\lua_escape:e {#2}') }
		\group_end:
	}
