package member naming rules unclear?

[loldrup]

On this page https://ceylon-lang.org/documentation/1.3/tour/modules/

under the headline "Source files and packages"

it is said that: "There's no package statement in Ceylon source files. The compiler determines the package and module to which a toplevel program element belongs by the location of the source file in which it is declared."

Then an (interesting!) example is given: "For example, if source is a source directory, and if a class named Hello is defined in the file source/org/jboss/hello/Hello.ceylon, then Hello belongs to the package org.jboss.hello."

This example leaves one question open: Why was the package member named Hello? Was it because the file was named Hello.ceylon? Or because a class in the file was named Hello? And what happens if there is no correspondence between file name and class name?

Now that I'm thinking more about it, I can kinda figure out that it must be the file name that determines the name of the package member. But it would still be nice having it stated explicit :)

[bjansen]

The file name does not affect declaration names. If a class named Hello is put in a file named World.ceylon, then the declaration name will be your.package::Hello.

To anwser your last sentence: package members are named after what's declared in the file, not after the file name. You can have multiple shared declarations in the same file, unlike in Java, that's why the file name is purely informal and is not used to determine member names.

[loldrup]

Hmm, that's confusing. When I read further on, in the section named 'Imports', I can sort of deduce that the syntax for importing 'program elements' into a source file is as follows:

import package_name { list of program elements' }

(I have to deduce this, as it isn't stated explicitly anywhere. My deduction is even made less certain due to the fact that this section doesn't reuse the /org/jboss/hello example introduced in the former section)

But then, if things have to be consistent, I can now conclude that a class cannot be a 'program element' (unless classes can be embedded in other classes - then the embedded class could be a 'program element'). I conclude this because top level classes in a source file becomes their own separate package, and the name of each of these classes becomes embedded in their respective package names. Having the class name thus 'eaten' by the package name must mean that the only the innards of a given to level class can be imported as the 'program element'. Right...?

Den 13/06/2017 4.41 PM skrev "Bastien Jansen" [email protected]:

The file name does not affect declaration names. If a class named Hello is put in a file named World.ceylon, then the declaration name will be your.package::Hello.

To anwser your last sentence: package members are named after what's declared in the file, not after the file name. You can have multiple shared declarations in the same file, unlike in Java, that's why the file name is purely informal and is not used to determine member names.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/ceylon/ceylon-lang.org/issues/473#issuecomment-308138611, or mute the thread https://github.com/notifications/unsubscribe-auth/AAP_NLYflK92pgprPsiJw3_YkiKkZC-lks5sDp98gaJpZM4N4kc5 .

[lucaswerkmeister]

I can now conclude that a class cannot be a 'program element' (unless classes can be embedded in other classes - then the embedded class could be a 'program element').

Classes can be embedded in other classes, just like other declarations. Ceylon allows you to embed class, interface or function declarations inside regular blocks and bodies.

I conclude this because top level classes in a source file becomes their own separate package, and the name of each of these classes becomes embedded in their respective package names.

No, classes don’t become a separate package. A class Hello defined in the file source/org/jboss/hello/_______.ceylon (where the ______ is arbitrary) belongs to the org.jboss.hello package. A toplevel function defined in the same file also belongs to the same package.

[loldrup]

Ah yes, I see now.

But it would still be neat if you would:

• Change the unfortunate example where the file name confusingly overlaps with the class name.
• Explicitly state that file names has no influence on package names. I know it can be inferred, but you can just start such a clarifying sentence with 'thus...'.
• Explicitly state the syntax for import declarations.
• Don't switch examples between the sections 'Source and file packages' and 'Imports'.

If these small paper cuts hadn't been there, I probably would have been able to read it without all my misunderstandings.

Mvh. Jon Loldrup

On 13 June 2017 at 23:39, Lucas Werkmeister [email protected] wrote:

I can now conclude that a class cannot be a 'program element' (unless classes can be embedded in other classes - then the embedded class could be a 'program element').

Classes can be embedded in other classes, just like other declarations. Ceylon allows you to embed class, interface or function declarations inside regular blocks and bodies.

I conclude this because top level classes in a source file becomes their own separate package, and the name of each of these classes becomes embedded in their respective package names.

No, classes don’t become a separate package. A class Hello defined in the file source/org/jboss/hello/_______.ceylon (where the ______ is arbitrary) belongs to the org.jboss.hello package. A toplevel function defined in the same file also belongs to the same package.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/ceylon/ceylon-lang.org/issues/473#issuecomment-308256679, or mute the thread https://github.com/notifications/unsubscribe-auth/AAP_NA8HnCWXscfkFAGRtUIuKX6Nwqctks5sDwGdgaJpZM4N4kc5 .

[lucaswerkmeister]

Change the unfortunate example where the file name confusingly overlaps with the class name.

I disagree that it’s an unfortunate example – it’s conventional in Ceylon to have classes in a file of their own, and to name the file after the class (i. e., put Hello in Hello.ceylon). I don’t like the idea of deviating from that convention just to drive home the fact that it’s a convention, not a requirement. I’d prefer to address only bullet point two, with something like:

Explicitly state that file names has no influence on package names.

Isn’t this what the next paragraph does?

Note that the name of the source file itself is not significant, as long as it has the extension .ceylon. It's only the directory in which the source file is located that matters to the compiler.

Explicitly state the syntax for import declarations.

How explicitly do you want it? A full grammar, in my opinion, belongs in the specification, not in the tour. On the other hand, the thrice repeated “we write” isn’t great either, and would perhaps be a good opportunity to explain the syntax non-formally: ”we write the package name and the imported declaration separately” (or something like that); “we list the program elements, separated by commas”; and “we use an ellipsis”, for example.

Adding an example for multiple imports would probably be a good idea too, so what if we added org.jboss.hello without removing com.redhat.polar.core?

import org.jboss.hello { Hello }
import com.redhat.polar.core { Polar }

[loldrup]

Den 14/06/2017 12.39 AM skrev "Lucas Werkmeister" <[email protected]

:

Change the unfortunate example where the file name confusingly overlaps with the class name.

I disagree that it’s an unfortunate example – it’s conventional in Ceylon to have classes in a file of their own, and to name the file after the class (i. e., put Hello in Hello.ceylon). I don’t like the idea of deviating from that convention just to drive home the fact that it’s a convention, not a requirement.

That isn't the point we're trying to drive home. The point is that file name has no effect on package name. One could make the example disambiguous (name the file name different from the class name) and then solve the missing convention compliance by following​ up with a sentence like this:

"however it is a Ceylon convention to put every top level class in a file on its own, having the same name as the class itself."

When I read the article earlier today, I didn't grasp from the text, that that's a convention. It would be a good thing for readers to know this, so why not put it in right there, explicitly? It's the perfect situational spot. The newbie is grasping for straws as to how he should organise his code, so that would be a gold nugget right there.

I’d prefer to address only bullet point two, with something like:

Explicitly state that file names has no influence on package names.

Isn’t this what the next paragraph does?

Note that the name of the source file itself is not significant, as long as it has the extension .ceylon. It's only the directory in which the source file is located that matters to the compiler.

In a way it does, yes, but vaguely. If it had said "Note that the name of a source file has no influence on the name of the package that contains its program elements" I would probably have noticed the fact right there. On top of that bit of vagueness, the current text then hurries on with ", as long as it has the extension .ceylon". However, it says this without then elaborating on what that special case is actually all about. Argh! Cliff hanger!

The next sentence then says: "It's only the directory in which the source file is located that matters to the compiler".

Again vague. It could have been "It's only the directory path that determines the package name."

Maybe this information should simply be moved up a bit. When I first read the first paragraph I got stuck there thinking hard about how I could deduce the missing information. I didn't want to skip the issue and just read on. Though it would have helped.

The first paragraph currently goes like this: "The compiler determines the package and module to which a toplevel program element belongs by the location of the source file in which it is declared"

How about extending this to:

"The compiler determines the package and module to which a toplevel program element belongs by the location of the source file in which it is declared. The name of the source file itself has no influence on the package name".

Problem solved?

Even though this would solve the specific problem, I think the whole ordeal could be stated even clearer:

"Every program element in a .ceylon source file belongs to a package. The name of that package is simply the directory path of the source file containing the program element. The name of the source file itself has no influence on the package name".

Now that is clear and succinct :D

Explicitly state the syntax for import declarations.

How explicitly do you want it?

Something like this:

import package_name { list_of_program_elements }

Or in "verbal" form, something like this:

"A package import statement consists of the word 'import' followed by the name of a package, followed by a list of program elements that are to be imported from that package.

"

...On the other hand, the thrice repeated “we write” isn’t great either, and would perhaps be a good opportunity to explain the syntax non-formally: ”we write the package name and the imported declaration separately”

I don't understand what you're trying to say with that sentence :/

“we list the program elements, separated by commas”; and “we use an ellipsis”, for example.

Well, it isn't necessary to state these details in "verbal" form, as they are communicated just fine be the example import statements. What the example import statements does not communicate is the types of the word parts ('this part is the package name', 'that part is the program elements names')

Adding an example for multiple imports would probably be a good idea too, so what if we added org.jboss.hello without removing com.redhat.polar.core?

import org.jboss.hello { Hello }import com.redhat.polar.core { Polar }

Good idea!

PS. I hope the term 'program element' has been well defined previously in the tour. Else it is used without proper introduction in this article :(

/Jon