[m-dev.] a question of terminology

[Zoltan Somogyi]

I have just started to work again on my diff for replacing item lists
with more structured representations, of the source code, of .int* files,
and .*opt files.

This involves working with code that deals with two distinct kinds of
interfaces. One notion of interfaces has to do with the kind of file being
represented: .int* as opposed to .m or .*opt. The other notion has to do
with the visibility of items outside their defining module, i.e. whether an
item is in a section that starts with ":- interface" or in one that starts with
":- implementation". The two are related, but not identical, since a .int
file can (and often does) have an implementation section. Call the two
notions "file kind" and "section kind".

Predicate and variable names in the existing code refer to interfaces in
both senses as "interface" or "int", which is often confusing. I have been
changing the code that talks about the file kind of interface to use "ifile"
instead of "int" and "noifile" to talk about things that don't do int .int* files,
but that is cumbersome. I have been thinking that it would be better
to switch away from the "interface" terminology for the other notion,
the notion of section kind. I am thinking of several possibilities, including
using "exported" or "exp" as an internal name in the compiler for the
interface section and "private" or "priv" or "pvt" for the implementation
section, or using "header/hdr" and "nonheader/nhdr" by analogy with C,
using "body" for nhdr by analogy to Ada, or "vis" and "invis", referring to
the external visibility of the section's contents, or maybe even mixing
metaphors a bit, with "vis" for the interface and "pvt" for the
implementation. External vs internal work as full words, but "int" as
an abbreviation of "internal" collides with "int" as an abbreviation of
"interface".

Note that several of these choices also conflict with other uses of
those terms, e.g. "private interfaces" are .int3 files, "headers" can refer
to kinds of foreign code inclusions, and "body" can refer to type definitions (referring to the parts of type definitions that don't survive when you
make the type definition abstract), though these collisions should cause
a lot less confusion that the two distinct senses of "interface".

Does anyone have any other suggestions, or opinions on the relative
or absolute desirability of any of these choices?

Zoltan.

[Paul Bone]

Post by Zoltan Somogyi
Predicate and variable names in the existing code refer to interfaces in
both senses as "interface" or "int", which is often confusing. I have been
changing the code that talks about the file kind of interface to use "ifile"
instead of "int" and "noifile" to talk about things that don't do int .int* files,
but that is cumbersome. I have been thinking that it would be better
to switch away from the "interface" terminology for the other notion,
the notion of section kind. I am thinking of several possibilities, including
using "exported" or "exp" as an internal name in the compiler for the
interface section and "private" or "priv" or "pvt" for the implementation
section, or using "header/hdr" and "nonheader/nhdr" by analogy with C,
using "body" for nhdr by analogy to Ada, or "vis" and "invis", referring to
the external visibility of the section's contents, or maybe even mixing
metaphors a bit, with "vis" for the interface and "pvt" for the
implementation. External vs internal work as full words, but "int" as
an abbreviation of "internal" collides with "int" as an abbreviation of
"interface".

I feel that visible and invisible are good choices. To me they say more
about what it *means* for something to be in the interface or implementation
section of a module. That is, from the perspective of the compiler, "is X
visible to Y?" is usually the question we want to answer (a declarative
perspective), "is X in Z's interface?" is just how we answer the question
(an operational perspective).

I made an attempt (but didn't have enough spare time in one large chunk) to
refactor the import status code based on one of your incomplete patches.
Having looked at this code and now thinking about new terminology it seems
there are multiple classes (more than one may be true).

+ A declaration is visible to all other modules.
+ A declaration is visible to sub-modules
+ A declaration is visible to only this module
+ A declaration is visible via opt-importing
+ A definition " " " " " (etc)

Visibility lets as talk about what code can see what other code.

Post by Zoltan Somogyi
Note that several of these choices also conflict with other uses of
those terms, e.g. "private interfaces" are .int3 files, "headers" can refer
to kinds of foreign code inclusions, and "body" can refer to type definitions (referring to the parts of type definitions that don't survive when you
make the type definition abstract), though these collisions should cause
a lot less confusion that the two distinct senses of "interface".

I would also avoid the term "external" because that has another meaning in
Mercury: that the definition of a locally defined predicate is external
(hand written in C).

[Zoltan Somogyi]

Post by Paul Bone
I feel that visible and invisible are good choices. To me they say more
about what it *means* for something to be in the interface or implementation
section of a module. That is, from the perspective of the compiler, "is X
visible to Y?" is usually the question we want to answer (a declarative
perspective), "is X in Z's interface?" is just how we answer the question
(an operational perspective).
I made an attempt (but didn't have enough spare time in one large chunk) to
refactor the import status code based on one of your incomplete patches.
Having looked at this code and now thinking about new terminology it seems
there are multiple classes (more than one may be true).
+ A declaration is visible to all other modules.
+ A declaration is visible to sub-modules
+ A declaration is visible to only this module
+ A declaration is visible via opt-importing
+ A definition " " " " " (etc)
Visibility lets as talk about what code can see what other code.

That is actually a point *againt* using this terminology in the context
of parts of modules, since there are only two sections in .m, .int* and
.*opt files, not all the ones you listed. Those gradations of visibility
are imposed on parts of the parse tree very late; most code that deals
with the parse tree does not start with knowing about them. The parts
of the compiler I am modifying do not *want* to talk about what code
can see what other code, because they do not yet have the information
needed to answer that question (though some of the more complex
of those parts have the job of figuring it out).

Post by Paul Bone

Post by Zoltan Somogyi
Note that several of these choices also conflict with other uses of
those terms, e.g. "private interfaces" are .int3 files, "headers" can refer
to kinds of foreign code inclusions, and "body" can refer to type definitions (referring to the parts of type definitions that don't survive when you
make the type definition abstract), though these collisions should cause
a lot less confusion that the two distinct senses of "interface".

I would also avoid the term "external" because that has another meaning in
Mercury: that the definition of a locally defined predicate is external
(hand written in C).

Which is why I started the above list of conflicts with "e.g.", signaling
that it is not a *complete* list of such conflicts.

I just thought of another alternative: referring to .int, .int2 .int3 and .int0
files internally as .hdr, .hdr2, .hdr3 and .hdr0, in predicate names
and variable names. That may be less disruptive than any of the other
schemes in my previous mail. Opinions?

Zoltan.

[Michael Day]

Post by Zoltan Somogyi
I just thought of another alternative: referring to .int, .int2 .int3 and .int0
files internally as .hdr, .hdr2, .hdr3 and .hdr0, in predicate names
and variable names. That may be less disruptive than any of the other
schemes in my previous mail. Opinions?

Personally not a fan of bringing "header files" back as a concept, but I
don't have much of a stake in the issue.

Michael

[Paul Bone]

Post by Zoltan Somogyi

Post by Paul Bone
I feel that visible and invisible are good choices. To me they say more
about what it *means* for something to be in the interface or implementation
section of a module. That is, from the perspective of the compiler, "is X
visible to Y?" is usually the question we want to answer (a declarative
perspective), "is X in Z's interface?" is just how we answer the question
(an operational perspective).
I made an attempt (but didn't have enough spare time in one large chunk) to
refactor the import status code based on one of your incomplete patches.
Having looked at this code and now thinking about new terminology it seems
there are multiple classes (more than one may be true).
+ A declaration is visible to all other modules.
+ A declaration is visible to sub-modules
+ A declaration is visible to only this module
+ A declaration is visible via opt-importing
+ A definition " " " " " (etc)
Visibility lets as talk about what code can see what other code.

That is actually a point *againt* using this terminology in the context
of parts of modules, since there are only two sections in .m, .int* and
.*opt files, not all the ones you listed. Those gradations of visibility
are imposed on parts of the parse tree very late; most code that deals
with the parse tree does not start with knowing about them. The parts
of the compiler I am modifying do not *want* to talk about what code
can see what other code, because they do not yet have the information
needed to answer that question (though some of the more complex
of those parts have the job of figuring it out).

Right, I wasn't sure if the part of the compiler (and terminology there)
affected the later import_status stuff. This is a less abstract perspective
and therefore I'd suggest terminology that's more operational/specific, so
maybe exported/not_exported or in_interface/not_in_interface is better.

Post by Zoltan Somogyi

Post by Paul Bone

Post by Zoltan Somogyi
Note that several of these choices also conflict with other uses of
those terms, e.g. "private interfaces" are .int3 files, "headers" can refer
to kinds of foreign code inclusions, and "body" can refer to type definitions (referring to the parts of type definitions that don't survive when you
make the type definition abstract), though these collisions should cause
a lot less confusion that the two distinct senses of "interface".

I would also avoid the term "external" because that has another meaning in
Mercury: that the definition of a locally defined predicate is external
(hand written in C).

Which is why I started the above list of conflicts with "e.g.", signaling
that it is not a *complete* list of such conflicts.

Yep, just another one that isn't perfect.

Post by Zoltan Somogyi
I just thought of another alternative: referring to .int, .int2 .int3 and .int0
files internally as .hdr, .hdr2, .hdr3 and .hdr0, in predicate names
and variable names. That may be less disruptive than any of the other
schemes in my previous mail. Opinions?

I can't think of any new alternatives, this one is amoung the
equally-least-objectionable alternatives. I agree with you about the
others, the terms with fewer and less subtle overloading are preferable.
I'm afraid I can't help further without bikeshedding for the sake of
bikeshedding.

Cheers.

[Peter Wang]

Post by Zoltan Somogyi
I just thought of another alternative: referring to .int, .int2 .int3 and .int0
files internally as .hdr, .hdr2, .hdr3 and .hdr0, in predicate names
and variable names. That may be less disruptive than any of the other
schemes in my previous mail. Opinions?

Declarations section, abbreviated as decl?

Wikipedia suggests another term for header files is "copybooks", which
is actually somewhat suggestive, if a term associated with COBOL is not
a problem ;)

Peter