[A68-JARGON][COMMITTED 1/2] New term: yin-yang
Jose E. Marchesi
jemarch@gnu.org
Tue Jun 2 20:41:09 GMT 2026
---
src/Makefile.am | 6 +-
src/a68-jargon.texi | 3 +
src/yin-yang.texi | 145 ++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 152 insertions(+), 2 deletions(-)
create mode 100644 src/yin-yang.texi
diff --git a/src/Makefile.am b/src/Makefile.am
index 1e75acd..fc684bf 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -72,7 +72,8 @@ a68_jargon_TEXINFOS = actual-declarer.texi \
void-unit.texi \
well-formedness.texi \
widening.texi \
- worthy-character.texi
+ worthy-character.texi \
+ yin-yang.texi
AM_MAKEINFOFLAGS = --set-customization-variable CHECK_NORMAL_MENU_STRUCTURE=true
@@ -137,7 +138,8 @@ man_MANS = a68-jargon.7algol \
void-unit.7algol \
well-formedness.7algol \
widening.7algol \
- worthy-character.7algol
+ worthy-character.7algol \
+ yin-yang.7algol
%.pod: %.texi
-$(top_srcdir)/contrib/texi2pod.pl -D $(notdir $(basename $<)) < $< > $@
diff --git a/src/a68-jargon.texi b/src/a68-jargon.texi
index 796ec28..18a6e4a 100644
--- a/src/a68-jargon.texi
+++ b/src/a68-jargon.texi
@@ -197,6 +197,7 @@ Language
* Well-Formedness::
* Widening::
* Worthy Character::
+* Yin-Yang::
@c * Yoneda Ambiguity::
@c * Unworthy Character::
@@ -418,6 +419,7 @@ Jose E. Marchesi <jemarch@gnu.org>
* Well-Formedness::
* Widening::
* Worthy Character::
+* Yin-Yang::
@end menu
@include actual-declarer.texi
@@ -466,6 +468,7 @@ Jose E. Marchesi <jemarch@gnu.org>
@include well-formedness.texi
@include widening.texi
@include worthy-character.texi
+@include yin-yang.texi
@node Implementation
@chapter Implementation
diff --git a/src/yin-yang.texi b/src/yin-yang.texi
new file mode 100644
index 0000000..feb5efa
--- /dev/null
+++ b/src/yin-yang.texi
@@ -0,0 +1,145 @@
+@c This file is part of the Algol 68 Jargon File.
+@c
+@c Copyright (C) 2026 Jose E. Marchesi
+@c
+@c You can redistribute and/or modify this document under the terms of
+@c the GNU General Public License as published by the Free Software
+@c Foundation, either version 3 of the License, or (at your option) any
+@c later version.
+@c
+@c Alternatively, permission is granted to copy, distribute and/or modify
+@c this document under the terms of the GNU Free Documentation License,
+@c Version 1.3 or any later version published by the Free Software
+@c Foundation; with no Invariant Sections, no Front-Cover Texts, and no
+@c Back-Cover Texts.
+
+@node Yin-Yang
+@section Yin-Yang
+
+@c man title yin-yang determining mode well-formedness
+
+@subheading Meaning
+@c man begin MEANING
+There is a certain level of recursion that may show in the data
+structures denoted by Algol 68 modes. A typical example are the nodes
+of linked lists, trees or graphs, in which each node must be able to
+somehow refer to the other nodes linked to themselves. This is great,
+but it was early recognized that this flexibility could be dangerous,
+for two reasons.
+
+First, should a mode be built in a way the recursion never stops,
+values of that mode would occupy infinite space, which makes no sense.
+This would be the case of @code{mode @B{Node} = struct (int data,
+@B{Node} next)} for example. The solution for this problem, a version
+of which was later adopted by C, was to go through the indirection
+implied by a name or reference. So we would write @code{mode @B{Node}
+= @B{struct} (@B{int} data, @B{ref} @B{Node} next)} instead.
+
+Second, recursion in mode definitions may lead to ambiguity in the
+context of strong syntactic positions and their associated coercions.
+Lindsey exemplifies this situation with a mode @code{mode @B{Itself} =
+@B{ref} @B{Itself}} and the right hand side (which is a strong
+position) in the assignation @code{@B{ref} @B{Itself} = @B{loc}
+@{Itself}.
+
+A mode declaration that doesn't suffer from any of the above problems
+is said to be @dfn{well formed}. Otherwise, it is said to be ill
+formed.
+
+On the face of these problems, the syntax of the mode declarers was
+carefully designed (like everything else in this language) so that, on
+one side, ill formed modes can always be detected at compile time and,
+on the other, the programmer can easily and consistently determine,
+without having to remember arbitrary rules, whether the mode she is
+writing is well formed. To this effect, both compiler and programmer
+use the same method: the so-called @dfn{yin-yang algorithm}, which is
+directly derived from the grammar of declarers (see below).
+
+The method is as follows:
+
+@itemize @bullet
+@item Start with the mode indicant being declared.
+@item When a @code{@B{ref}} or @code{@B{proc}} is found, that's a yin.
+@item When a @code{@B{struct}} or a procedure's parameter pack is found, that's a yang.
+@item At the point the initial mode indicant is found, if at least one yin and one yang have been found, the mode is well formed. Otherwise it is not.
+@end itemize
+
+Finding at last a yin guarantees that the problem of infinitely big
+data objects due to recursion cannot happen, and finding at least a
+yang guarantees that the mode is not strongly coercible to itself.
+
+As a first example, consider the declaration of the mode
+@code{@B{Node}} below:
+
+@example
+@B{mode} @B{Node} = @B{struct} (@B{int} data, @B{Node} next)
+@end example
+
+Applying the yin-yang method, we start with @code{@B{Node}}, then we
+get a yang due to the @code{@B{struct}}, thn we find @code{@B{Node}}
+again: there is recursion. But since we didn't get any yin, the mode
+is not well formed because its values would occupy infinite space. To
+fix this, we make sure to add a yang via either a name or a procedure:
+
+@example
+@B{mode} @B{Node} = @B{struct} (@B{int} data, @B{ref} @B{Node} next)
+@end example
+
+As a second example, consider the declaration of the mode
+@code{@B{Set}} below:
+
+@example
+@B{mode} @B{Set} = @B{ref}[]@B{Elem},
+ @B{Elem} = @B{union} (@B{int},@B{Set})
+@end example
+
+Applying the yin-yang method, we start with @code{@B{Set}}, then we
+get a yin due to the @code{@B{ref}}, then we find @code{@B{Elem}}, in
+which we find @code{@B{Set}} again: there is recursion. But since we
+didn't get any yang, the mode is not well formed because it is
+strongly coercible to itself: a value of mode @code{@B{Set}} could be
+dereferenced, then rowed, then united. To fix this, we make sure to
+add a yang:
+
+@example
+@B{begin} @B{mode} @B{Set} = @B{struct} (@B{ref}[]@B{Elem} elems),
+ @B{Elem} = @B{union} (@B{int},@B{Set});
+@end example
+@c man end
+
+@subheading Syntax
+@c man begin SYNTAX
+Simplified [RR 7.4.1]:
+
+@example
+a) WHETHER (NOTION) shields SAFE to SAFE:safe
+ where (NOTION) is (PLAIN)
+ or (NOTION) is (FLEXETY ROWS of)
+ or (NOTION) is (union of) or (NOTION) is (void),
+ WHETHER true.
+
+b) WHETHER (PREF) shields SAFE to yin SAFE: WHETHER true.
+
+c) WHETHER (structured with) shields SAFE to yang SAFE:
+ WHETHER true.
+
+d) WHETHER (procedure with) shields SAFE to yin yang SAFE:
+ WHETHER true.
+@end example
+@c man end
+
+@subheading See Also
+
+@itemize @bullet
+@item [RR 7.4.1]
+@item [II 2.4.3]
+@end itemize
+
+@ignore
+@c man begin AUTHOR
+Jose E. Marchesi <jemarch@gnu.org>
+@c man end
+@c man begin SEEALSO
+[RR 7.4.1], [II 2.4.3]
+@c man end
+@end ignore
--
2.39.5
More information about the Algol68
mailing list