diff options
Diffstat (limited to 'macros/optex/base/prefixed.opm')
| -rw-r--r-- | macros/optex/base/prefixed.opm | 73 |
1 files changed, 47 insertions, 26 deletions
diff --git a/macros/optex/base/prefixed.opm b/macros/optex/base/prefixed.opm index 61df791ddb..f8edf5d135 100644 --- a/macros/optex/base/prefixed.opm +++ b/macros/optex/base/prefixed.opm @@ -1,6 +1,6 @@ %% This is part of the OpTeX project, see http://petr.olsak.net/optex -\_codedecl \public {Prefixing and code syntax <2020-02-14>} % preloaded in format +\_codedecl \public {Prefixing and code syntax <2020-02-25>} % preloaded in format \_doc --------- All \TeX/ primitives have alternative control sequence `\_hbox` `\_string`, ... @@ -27,6 +27,10 @@ \`\private` `<sequence> <sequence> ...;` does `\let \_<sequence> = \<sequence>` for all sequences. \nl + \`\_checkexists` `<where> <prefix><sequence>` prints error + if the control sequence propagated to + a new name space by `\public` etc. macros is not declared. + \nl \`\xargs` `<what> <sequence> <sequence> ... ;` does `<what><sequence>` for each sequences. \_cod ----------------- @@ -37,11 +41,18 @@ \_def \_pkglabel{} \_def \_public {\_xargs \_publicA} -\_def \_publicA #1{\_ea\_let \_ea#1\_csname _\_csstring #1\_endcsname} - +\_def \_publicA #1{% + \_checkexists \public _#1% + \_ea\_let \_ea#1\_csname _\_csstring #1\_endcsname +} \_def \_private {\_xargs \_privateA} -\_def \_privateA #1{\_ea\_let \_csname _\_csstring #1\_endcsname =#1} - +\_def \_privateA #1{% + \_checkexists \private {}#1% + \_ea\_let \_csname _\_csstring #1\_endcsname =#1% +} +\_def\_checkexists #1#2#3{\_unless \_ifcsname #2\_csstring#3\_endcsname + \_errmessage {\_string#1: \_bslash#2\_csstring#3 must be declared}\_fi +} \_public \public \private \xargs \ea ; \_doc ----------------------- @@ -101,12 +112,16 @@ \_def \_nspublic {\_xargs \_nspublicA} \_def \_nspublicA #1{% + \_checkexists \nspublic {\_pkglabel _}#1% \_unless\_ifx #1\_undefined \_opwarning{\_ea\_ignoreit\_pkglabel\_space redefines the meaning of \_string#1}\_fi - \_ea\_let \_ea#1\_csname \_pkglabel _\_csstring #1\_endcsname} - + \_ea\_let \_ea#1\_csname \_pkglabel _\_csstring #1\_endcsname +} \_def \_nsprivate {\_xargs \_nsprivateA} -\_def \_nsprivateA #1{\_ea\_let \_csname \_pkglabel _\_csstring #1\_endcsname =#1} +\_def \_nsprivateA #1{% + \_checkexists \nsprivate {}#1% + \_ea\_let \_csname \_pkglabel _\_csstring #1\_endcsname =#1% +} \_endcode %---------------------------------------------------- @@ -117,8 +132,8 @@ \secc Prefixing internal control sequences All control sequences used in \OpTeX/ are used and defined with `_` prefix. -The user can be sure that when he/she does `\def\foo` then internal macros of -\OpTeX/ nor \TeX/ primitives will be not damaged. For example +The user can be sure that when he/she does `\def\foo` then neither internal macros of +\OpTeX/ nor \TeX/ primitives will be damaged. For example `\def\if{...}` will not damage macros because \OpTeX/'s macros are using `\_if` instead of `\if`. @@ -127,18 +142,18 @@ sequences: `\word` and `\_word`, for example `\hbox` and `\_hbox`. The first alternative is reserved for users or such control sequences can be re-defined by a user. -\OpTeX/ sets the character `_` as the letter, so it can be used in +\OpTeX/ sets the character `_` as letter, so it can be used in control sequences. When a control sequence begins with this character then it means that it is a primitive or it is used in \OpTeX/ macros as internal. User can redefine such prefixed control sequence only -if he/she explicitly know what happens. +if he/she explicitly knows what happens. We never change catcode of `_`, so internal macros can be -redefined by user without problems if it is desired. We need not -something like `\makealetter` from \LaTeX/. +redefined by user without problems if it is desired. We don't need +something like `\makeatletter` from \LaTeX/. \OpTeX/ defines all new macros as prefixed. For public usage of such macros, -we need to set non-prefixed version. This is done by +we need to set their non-prefixed versions. This is done by \begtt \catcode`\<=13 \public <list of control sequences> ; @@ -147,9 +162,9 @@ we need to set non-prefixed version. This is done by For example \^`\public`` \foo \bar ;` does `\let\foo=\_foo`, `\let\bar=\_bar`. At the end of each code segment in \OpTeX/, the `\_public` macro is used. You -can see, what macros are defined for public usage in this code segment. +can see which macros are defined for public usage in that code segment. -The macro \^`\private` does a reverse job to `\public` with the same syntax. +The macro \^`\private` does the reverse job of `\public` with the same syntax. For example `\private \foo \bar ;` does `\let\_foo=\foo`, `\let\_bar=\bar`. This should be used when an unprefixed variant of a control sequence is declared already but we need the prefixed variant too. @@ -163,7 +178,7 @@ and then the \^`\public` (or `\_public`) macro is used. Users can define or declare any control sequence with a name without any `_`. This does not make any problem. Only one exception is the reserved control -sequence `\par`. It is generated by tokenizer (at empty lines) +sequence `\par`. It is generated by the tokenizer (at empty lines) and used as internal in \TeX/. User can define or declare control sequences with `_` character, for @@ -172,7 +187,7 @@ example `\my_control_sequence`, but with the following exceptions: \begitems * Control sequences which begin with `_` are reserved for \TeX/ primitives, \OpTeX/ internal macros and packages internal macros. -* Control sequences (terminated by non-letter) in the form +* Multiletter control sequences in the form `\<word>_` or `\<word>_<one-letter>`, where <word> is a sequence of letters, are inaccessible, because they are interpreted as `\<word>` followed by `_` or as `\<word>` followed by @@ -182,7 +197,7 @@ example `\my_control_sequence`, but with the following exceptions: \max-M ... is interpreted as \max _M \alpha-{ij} ... is interpreted as \alpha _{ij} \endtt - This feature is implemented using lua code at input processor level, see + This feature is implemented using Lua code at input processor level, see the section~\ref[math-macros] for more details. You can deactivate this feature by \^`\mathsboff`. After this, you can still write `$`$\int$`_a^b$` (Unicode) or `$\int _a^b$` % $∫_a^b$ (Unicode) or $\int _a^b$ @@ -226,7 +241,7 @@ Package writer should use internal names in the form `\_<pgk>_<sequence>`, where `<pkg>` is a package label. For example: `\_qr_utfstring` from `qrcode.opm` package. -The package writer needs not to write repeatedly `\_pkg_foo` `\_pkg_bar` +The package writer does not need to write repeatedly `\_pkg_foo` `\_pkg_bar` etc.\ again and again in the macro file.\fnote {We have not adopted the idea from expl3 language:)} When the \^`\_namespace` `{<pkg>}` @@ -265,8 +280,8 @@ If you are writing a macro file that is intended to be published for \begitems * Don't use control sequences from the user namespace in the macro - bodies if there is not explicit and documented reason to do this. -* Don't declare control sequences in the user namespace if there are not + bodies if there is no explicit and documented reason to do this. +* Don't declare control sequences in the user namespace if there are no explicit and documented reasons to do this. * Use control sequences from \OpTeX/ and primitive namespace in read-only mode, if there is not an explicit and documented reason to @@ -279,14 +294,19 @@ If you are writing a macro file that is intended to be published for twice if another macro or the user needs it explicitly too. * Use \^`\_codedecl` as your first command in the macro file and \^`\_endcode` to close the text of macros. -* Use \^`\_doc` ... \^`\_cod` pairs for documenting the code pieces and/or write - more documentation after the \^`\_endcode` command. +* Use \^`\_doc` ... \^`\_cod` pairs for documenting the code pieces. +* You can write more documentation after the \^`\_endcode` command. +* The \OpTeX/ catcodes are set when \^`\load` your package (i.e. plain \TeX/ + catcodes plus catcode of `_` is 11). If a catcode is changed during + loading your package then it is forgot because \^`\load` returns to catcodes + used before loading package. If you want to offer a catcode changing for + users then insert it to a macro which can be used after loading. \enditems If the macro file accepts these recommendations then it should be named by `<filename>.opm` where `<filename>` differs from file names used directly in \OpTeX/ and from other published macros. -This extension `opm` has precedence before `.tex` when +This extension `.opm` has precedence before `.tex` when the \^`\load` macro is used. The `qrcode.opm` is the first example of how an external macro file for \OpTeX/ @@ -294,5 +314,6 @@ can look like. \endinput +2021-04-25 \_checkexists introduced 2021-02-15 \_expandafter -> \_ea in \_codedecl 2020-02-14 released |