summaryrefslogtreecommitdiff
path: root/macros/optex/base/prefixed.opm
diff options
context:
space:
mode:
Diffstat (limited to 'macros/optex/base/prefixed.opm')
-rw-r--r--macros/optex/base/prefixed.opm73
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