%% This is part of the OpTeX project, see http://petr.olsak.net/optex

\_codedecl \sdef {Basic macros for OpTeX <2023-11-11>} % preloaded in format

   \_doc ------------------------------
   \`\bgroup`, \`\egroup`, \`\empty`, \`\space`, and \`\null`
   are classical macros from plain \TeX/.
   \_cod ------------------------------

\_let\_bgroup={  \_let\_egroup=}
\_def \_empty {}
\_def \_space { }
\_def \_null {\_hbox{}}
\_public \bgroup \egroup \empty \space \null ;

   \_doc ------------------------------
   \`\ignoreit` ignores next token or `{<text>}`,
   \`\useit``{<text>}` expands to `<text>` (removes outer braces),
   \`\ignoresecond` uses first, ignores second parameter and
   \`\usesecond` ignores first, uses second parameter.
   \_cod ------------------------------

\_long\_def \_ignoreit #1{}
\_long\_def \_useit #1{#1}
\_long\_def \_ignoresecond #1#2{#1}
\_long\_def \_usesecond #1#2{#2}
\_public \ignoreit \useit \ignoresecond \usesecond ;

   \_doc ------------------------------
   \`\bslash` is \"normal backslash" with category code 12.
   \`\nbb` is double backslash
   and \`\pcent` is normal~`%`.
   They can be used in Lua codes, for example.
   \_cod ------------------------------

\_edef \_bslash {\_csstring\\}
\_edef \_nbb {\_bslash\_bslash}
\_edef \_pcent{\_csstring\%}
\_public \bslash \nbb \pcent ;

   \_doc ------------------------------
   \`\sdef` `{<text>}` is equivalent to `\def\<text>`, where `\<text>` is a control
   sequence. You can use arbitrary parameter mask after `\sdef{<text>}`, don't
   put the (unwanted) space immediately after closing brace \code{\}}.
   \nl
   \`\sxdef` `{<text>}` is equivalent to `\xdef\<text>`.
   \nl
   \`\slet` `{<textA>}{<textB>}` is equivalent to `\let \<textA> = \<textB>`.
   \_cod ------------------------------

\_def \_sdef #1{\_ea\_def \_csname#1\_endcsname}
\_def \_sxdef #1{\_ea\_xdef \_csname#1\_endcsname}
\_def \_slet #1#2{\_ea\_let \_csname#1\_ea\_endcsname
   \_ifcsname#2\_ea\_endcsname \_begincsname#2\_endcsname \_else \_undefined \_fi
}
\_public \sdef \sxdef \slet ;

   \_doc ------------------------------
   \`\adef` `<char>{<body>}` defines active `<char>` as <body> and then
   puts the <char> as active character. I.e. the `<body>` can include the
   <char> as non-active charter (if it is non-active before `\adef`).
   For example `\adef ?{\,?}`.
   If the character is special, you can escape it, for example `\adef\%{...}`.
   The space can be declared by `\adef{ }{<body>}`.
   You can declare a macro with parameters too, for example
   `\adef @#1{...#1...}`. You can use prefixes `\protected`, `\global`,
   `\long` before `\adef`, they behave like prefixes before `\def`.
   \_cod ------------------------------

\_def\_adef#1#2#{\_adefA{#1}{#2}}
\_def\_adefA#1#2#3{\_ea\_def\_directlua{tex.cprint(13,"\_luaescapestring{\_csstring#1}")}#2{#3}%
   \_catcode`#1=13 }
\_public \adef ;

   \_doc ------------------------------
   \`\cs` `{<text>}` is only a shortcut to `\csname <text>\endcsname`, but you need
   one more `\_ea` if you need to get the real control sequence `\<text>`.
   \nl
   \`\trycs` `{<csname>}{<text>}` expands to `\<csname>`
   if it is defined else to the `<text>`.
   \_cod ------------------------------

\_def \_cs #1{\_csname#1\_endcsname}
\_def \_trycs#1#2{\_ifcsname #1\_endcsname \_csname #1\_ea\_endcsname \_else \_afterfi{#2}\_fi}
\_public \cs \trycs ;

   \_doc ------------------------------
   \`\addto` `\macro{<text>}` adds `<text>` to your `\macro`, which must be defined.\nl
   \`\aheadto` `\macro{<text>}` defines `\macro` as `<text>` followed by the
   original `\macro` body.
   \_cod ------------------------------

\_long\_def \_addto #1#2{\_ea\_def\_ea#1\_ea{#1#2}}
\_long\_def \_aheadto #1#2{\_edef#1{\_unexpanded{#2}\_unexpanded\_ea{#1}}}

\_public \addto \aheadto ;

   \_doc -----------------------------
   \`\incr``<counter>` increases `<counter>` by one globally.
   \`\decr``<counter>` decreases `<counter>` by one globally.
   \_cod -----------------------------

\_def\_incr #1{\_global\_advance#1by1 }
\_def\_decr #1{\_global\_advance#1by-1 }
\_public \incr \decr ;

   \_doc ------------------------------
   \`\opwarning` `{<text>}` prints warning on the terminal and to the log file.
   \_cod ------------------------------

\_def \_opwarning #1{\_wterm{WARNING l.\_the\_inputlineno: #1.}}
\_public \opwarning ;

   \_doc ------------------------------
   \`\loggingall` and \`\tracingall` are defined similarly as in
   plain \TeX/, but they print
   more logging information to the log file and the terminal.
   \_cod ------------------------------

\_def\_loggingall{
  \_tracingstats=2 \_tracingpages=1
  \_tracingoutput=1 \_tracingmacros=3 % \_tracinglostchars=2 is already set
  \_tracingparagraphs=1 \_tracingscantokens=1 \_tracingifs=1 \_tracinggroups=1
  \_tracingcommands=3 \_tracingrestores=1 \_tracingassigns=1 }
\_def\_tracingall{\_tracingonline=1 \_loggingall}
\_public \loggingall \tracingall ;

   \_doc ------------------------
   The `\optexversion` and `\fmtname` are defined in the `optex.ini` file.
   Maybe, somebody will need a private version of these macros.
   We add \`\_banner` used in `\everyjob` and in \~`\docgen`
   \_cod ------------------------

\_def\_banner {This is OpTeX (Olsak's Plain TeX), version <\_optexversion>}%
\_private \optexversion \fmtname ;

   \_doc ------------------------------
   \`\_byehook` is used in the \^`\bye` macro.
   Write a warning if the user did not load a Unicode Font.
   Write a \"rerun" warning if the `.ref` file was newly created or it was
   changed (compared to the previous TeX run).
   \_cod ------------------------------

\_def\_byehook{%
   \_ifx\_initunifonts\_relax \_relax\_else \_opwarning{Unicode font was not loaded}\_fi
   \_immediate\_closeout\_reffile
   \_edef\_tmp{\_mdfive{\_jobname.ref}}%
   \_ifx\_tmp\_prevrefhash\_else \_opwarning{Try to rerun,
      \_jobname.ref file was \_ifx\_prevrefhash\_empty created\_else changed\_fi}\_fi
}

\_endcode % -------------------------------------

2023-11-11: \adef reimplemented, \protected, \long, \global allowed before \adef
2023-01-22: \trycs: afterfi used for second parameter
2022-11-22: \_banner definition moved here
2022-11-18: \ahead introduced
2022-10-29: \_fin introduced
2021-07-20: \_unresovedrefs removed from \_byehook
2021-07-18: \_byehook: checking `ref` file consistency added.
2021-05-16: \slet reimplemented (to allow \slet{foo}{undefined}).
2021-02-03: \useit defined.
2021-01-22: \trycs: \ea added in order to be able to use cs with parameters
2021-01-08: \opwarning format changed (secondly, hope that conclusively)
2020-10-12: \opwarning: line numbers added
2020-02-14: introduced
