First a few comments on your language.  In three you talk about "calling
children()".  Well, "children()" is a module that you can call any place a
module is allowed.  Another module can call it many times, and it need not
be at the end of anything.  Maybe you meant "children".

Another problem with the language is that modules may "call" other modules,
including children(), but they do that within the module definition, which
is not available to us for built-in modules.  When you are using a module
you write the modules name and then you give it a list of children, in
braces if there are more than one.  I would not describe this relationship
as "the module calling" the children.  It's more like the module "has"
children.  They are there for the module to use, which is can do any number
of times.    Also if you have an expression like

color("red")
translate([0,3,0])
sphere(r=4);

then color() is the first module.  It has one child which is
"translate([0.3,0])sphere(r=4)".  The notion that the child (children?) is
somehow last is mistaken.  Every module not followed immediately by a ";"
character has children.  Furthermore, you don't seem to be clearly
acknowledging that there might be more than 1 child.  For example:

color("red") { cube(5); translate([0,3,0]) sphere(r=4);}

Now the color module has 2 children.  Again, nothing is "called" they are
simply the children provided to the color module.

The problem is that your "real terms" aren't right because a module can
both draw geometry and call children.  Consider:

module both(size)
{
right(size*1.5) children();
cube(size);
}

both(10) sphere(4);

It draws a shape but also it acts on its children.  And both() can appear
anywhere in what you're calling a statement.  Based on your list it fails
2 because it can call children and it fails 3 because it need not call
children.  So it doesn't fit in your classification.  If your goal is to
classify ONLY the built-in modules in native OpenSCAD without any broader
applicability (no libraries or user written code) then I think it does
cover the (currently) available modules, but it's not fully general and it
also doesn't cover modules found in libraries or the range of what can be
written.  In other words, it's not a fundamental characteristic of modules
but more like a pragmatic division of the native modules.

In the BOSL2 library, for example, the cuboid() module draws geometry and
can be invoked without children, but it also optionally accepts children
and runs them.  There are very few modules in BOSL2 that satisfy condition
2 on your list because almost everything that creates geometry also accepts
children, and furthermore, BOSL2 redefines most of the native modules to
match BOSL2's general behavior.

So in BOSL2:

include<BOSL2/std.scad>
cuboid(10) attach(RIGHT,BOT) cyl(r=5,h=10);

produces this:
[image: image.png]

On Thu, Jul 31, 2025 at 7:02 PM vulcan_--- via Discuss <
discuss@lists.openscad.org> wrote:

An example of a module that creates geometry and places children is a
washer in NopSCADlib that draws a washer but if it has a child it places it
on top. The child could be a screw or a nut or a second washer.

On Sat, 2 Aug 2025, 23:20 vulcan_--- via Discuss, <
discuss@lists.openscad.org> wrote:

Vulcan,

Let me note that I'm involved in the BOSL2 project, which consumes a lot of
my time and effort and I don't have time to deeply review your
documentation effort for OpenSCAD.  I know OpenSCAD well and almost never
refer to its manual, so I'm not exactly the audience.  I'm not sure why
expert coders would need a language reference.  I only need to occasionally
look up how search() works or other things like that, mainly because the
way search() works is ridiculous.

I do have a bit of a concern that you seem to be trying to (re)write the
OpenSCAD manual while having a somewhat shallow and incomplete
understanding of OpenSCAD.

I think you do not understand how modules are defined and how children
work.  It is absolutely incorrect to describe modules as "calling"
children, in my opinion.  The best word would be that children are
"passed".

Users can define modules in their code, they aren't just magical things
provided by the language.  A module defined by a user can call other
modules in the normal sense of "calling".  That looks like this:

module foo(input)
{
other_module(3*input);
}

In this example, the module foo() has called the module other_module().
You would invoke foo by writing "foo(17);" in your code, perhaps.  And we
can see that foo() makes no use of children.

If you have a module that uses children, perhaps bar(), then when you call
it, you might write this:

bar(24) child();

In this case, bar() is being run and given one child.  I maintain that bar
does not "call" the child in this construction.  The most standard way to
describe the relationship is that the child is PASSED to bar as a
parameter, but it's a different kind of parameter than a variable.  It's a
parameter which is geometry, or I guess what you want to call "shape".
(I'm not a great fan of "shape" because geometry can be several
shapes...but I'm also used to calling it geometry.  That's what we call it
in the BOSL2 manual.)  So the other way to invoke bar() with children is
this:

bar(24)
{
child1();
child2();
child3();
}

Here I have passed three children to bar().  Again, in this code, no
children have been "called".  The children are parameters which are
geometry (shape) instead of data and they are being passed into bar which
can use them or ignore them as it chooses.

Now within bar() I may want to use the children.  The way to do that is to
call the children() module.  This is an ordinary module that invokes all of
the children of the current module().  I guess in your language it "draws
the shape" of the children.  The bar() module can call children() never,
or once, or as many times as it likes, just like with any other kind of
parameter.  It can also do children(0) which "draws the shape" of the first
child, which I called child1() above.

It MAY be a useful taxonomy for the native modules to split them apart into
shape modules and operator modules.  I don't know.  But it's important to
be aware that this doesn't apply to ALL modules, only the native ones
currently in existence.  But this is kind of like saying that in the C
language functions can either return a computed value or they can print
output.  It's an incomplete taxonomy of what functions in C can do.

Another thing to consider here is that a beginning user will be using the
modules provided by native OpenSCAD.  But as the user advances just a bit
they will start writing their own modules which may or may not fit into the
above framework.  Writing your own modules is not some kind of advanced
thing---it's a basic approach for creating readable code.  And if the user
chooses to use libraries like BOSL2 or NopSCADlib they will encounter
modules in those libraries that do not fit into the above framework.  As
previously noted, in BOSL2 every module that "draws a shape" also accepts
children---with very few exceptions.  It's probably a better dichotomy if
you say that there are modules that REQUIRE children and then modules that
do NOT require children.  I suggest that if you present a classification
of module types, make sure it is complete, in the sense that it covers
every possible kind of module and then indicate that the NATIVE modules all
fit into just these two classes, whereas modules defined by libraries or
that you define yourself may fit into this or these other classes.

I have no clue what you mean about preserving the state of special
variables on a stack.

An open brace actually does NOT create a new scope when used in isolation.
You can see this by doing

a=3;
{
a=2;
echo(a);
}

If a new scope was created, this would run without warnings, but it gives a
reassignment warning when a=2 is assigned.  There was talk in the past of
making isolated braces invalid, actually.

If the braces are used to pass children to a parent, then they create a new
scope.  Hence this works:

a=3;
assert(true)
{
a=2;
echo(a);
}

Now the stuff in braces forms children to the assert() module and it
creates a new scope.  When you open a new scope like this all previously
existing variables are preserved, and new variables---which may have the
same name and hence hide the old ones---can be created in the new scope.
The same thing happens with let().  This can make it appear that you can
redefine variables, like above where I "redefined" a, but it only works
because the "redefinition" is in a new scope.

On Sat, Aug 2, 2025 at 6:20 PM vulcan_--- via Discuss <
discuss@lists.openscad.org> wrote:

I share this concern.  I welcome your helpful participation, but worry
that the result may require a lot of re-work.

On 8/2/2025 8:37 PM, Adrian Mariano via Discuss wrote:

--
This email has been checked for viruses by AVG antivirus software.
www.avg.com

[ Sigh.  I hate being away from my desktop environment.  Sorry for the
duplicate. ]

On 8/2/2025 3:20 PM, vulcan_--- via Discuss wrote:

Modules are modules and functions are functions.  There is no such thing
as one pretending to be the other.

object() is a function, period.

No, absolutely not.  The word "render" is well-defined in OpenSCAD to
refer to the process of reducing a model to a mesh. It most specifically
does not refer to the process of previewing a model.  Yes, abstractly
that is a form of rendering, but it is not what the word means in OpenSCAD.

children() is a module that invokes the operations that were passed to
the current module as its children.

As previously discussed, "operator module" and "object module" are a
false dichotomy, perhaps useful as a simple mental distinction but not
useful for formally describing OpenSCAD modules.  OpenSCAD modules may
accept zero or more children.  They may add shapes of their own, or they
may not.  They always yield a shape, though that shape may be empty. 
children() does not neatly fall into either the "operator" or "object"
classification, because it does not accept children, and does not
produce shapes of its own; it invokes the children of the current module
instantiation.

There are only three "funky operators" - let, echo, and assert - and
they only apply in expression context, just as operators like + and -
only apply in expression context.

The debate is over what to call the relationship between A and B in

A() B();

It is formally not correct to say that that line calls B.  Nor is it
truly correct to say that A calls B.  That line calls A, which might or
might not ... invoke ... the following statement that then calls B.

But how to say that in a way that is both technically correct and is
accessible to a newbie is difficult.

Long, long before that.  8008 is 1970s; FORTRAN is 1950s.  I don't know
what's before that, but something is.

Actually, the resulting CSG tree is pretty closely tied to the execution
process.

Not exactly.  It's really the parent module invocation that creates the
scope.  Braces by themselves do not create scopes (sigh).

It's a little hard to see this, but let() and for() demonstrate it; they
create a scope without needing braces to do it.

$ variables are accessible to the scope that creates them and to all
scopes called by that scope.

No.  Braces do not themselves create children.  Braces group children. 
If you have only one child, braces are not required.

A() { B(); }

is exactly equivalent to

A() B();

Increasingly untrue.  These days, pretty much as soon as somebody asks a
tricky question, the answer is "go look at BOSL2, it solves that
problem"... and for BOSL2, modules that create shapes and operate on
their children are almost universal.

The core set of modules doesn't include any that create shapes and
consume children.

That only arises from the implications of children(), that there is no
reason that you can't create shapes from a module that also calls
children().

I suppose that it depends on your definition of "hard", but I think
there are at least hundreds of thousands of lines of OpenSCAD programs
that would disagree.  (I mean, I can account for over over 10K in one
project alone, and BOSL2 is 77K...)

Is it different?  Sure.  And some aspects are really tricky, probably
trickier than other languages.  But you can do something moderately
complex without needing to explore the dark corners.

Writing documentation, on the other hand, is hard, because it needs to
both correctly describe those dark corners and be accessible to
beginners.  I think the answer to that is what's sometimes called
"progressive disclosure", where you present a simplified view, and then
introduce more advanced concepts as the user progresses.

That's pretty straightforward for tutorial matter, where you control the
intended order that the user reads the documentation. It's harder for
reference material, where you don't know in advance how deep the user
wants to go.  But even then you can take care to use language that is
simple but formally correct, and to introduce simpler aspects of a
particular topic before more advanced aspects.

Some documentation I read once - I dimly think it was the TeX manual -
specifically said in its introduction that it would lie to you, that it
would give you an incorrect but simplified and useful view of a topic,
and then would later correct it with more advanced concepts.  I think
that's a useful model.

Mostly, group 1 doesn't look at the documentation because they already
have everything in their head.

But also there's group 3:  non-programmers.  They form a significant
fraction of the user base.

Many of the concepts in this discussion, especially those around the
"child" relationship, are easier to talk about if you talk about lambda
functions... but those are a fairly advanced programming concept that
you don't really need to get into as a beginner; you can use the
mechanisms without needing to dive into that level of detail.

[ Going dark for a couple of days, en route from Scotland to Iceland. ]

HI Jordan .. i know it will be a while before you see this, but i wanted to reply to one small issue you raised

ah .. that scad assigns that specific meaning to “render” was not made clear to my until i read your message just now.

You know that my use of render, to process a model to create an image, is the standard use in the industry, yes?

In my experience the operation of making a polygonal version of the shapes in a model is “tessellation“

I did note that the terms, if you will, of “F5” and “F6” in the documentation seemed to carry more weight than just to indicate which function key to press. But after using them both i concluded that “F6” was a short form for “tessellation“ as its operation is to divide any face with more than 3 edges into triangles.

I have learned that the result of running an scad script is a mesh .. but, at least for primitives, drawn in n-gons .. so the term rendering does not seem to apply, to me. But i bow to the linguistic convention of the group.

er .. i hope that my readers understand that i am not being facetious saying this .. my career was based on my being able to establish good communications between my teams and those around us, and within the teams themselves, by creating and promoting language specific to each project and its corporate environment.

That was what i did in every job, so i am doing it here too

and .. this one

First, .. what is an “empty shape“ ?

on the face of it that makes little sense. If there is nothing displayed in the preview there was no mesh made, right?

I do get, now, that a module may create shape(s) itself, or be a parent to children that may create shapes. And that a module might perform only operations like color(), translate(), assert() and the like, thus defining what i have been calling an operator module, does not create any mesh, though its children might

so how can a module always yield a shape?

If you intersect two shapes that don't overlap or difference a shape that
completely overlaps the first operand, then you get an empty shape. It is
an empty geometry object.

All modules return a shape, but it may be empty.

On Tue, 5 Aug 2025, 22:51 vulcan_--- via Discuss, <
discuss@lists.openscad.org> wrote: