package member naming rules unclear? #473
Comments
|
The file name does not affect declaration names. If a class named 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 |
|
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" <notifications@github.com>:
… 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
<#473 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAP_NLYflK92pgprPsiJw3_YkiKkZC-lks5sDp98gaJpZM4N4kc5>
.
|
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.
No, classes don’t become a separate package. A class |
|
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 ***@***.***> 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
<#473 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAP_NA8HnCWXscfkFAGRtUIuKX6Nwqctks5sDwGdgaJpZM4N4kc5>
.
|
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
Isn’t this what the next paragraph does?
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 import org.jboss.hello { Hello }
import com.redhat.polar.core { Polar } |
|
Den 14/06/2017 12.39 AM skrev "Lucas Werkmeister" <notifications@github.com
:
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.
<example goes here>"
...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
|
The introductory paragraph of the “Packages and imports” section dealt mostly with packages, not with imports, and went into a lot of detail. It has been updated to give a more high-level overview of both aspects, and leave the detail to its subsections. The introduction to packages did not make it clear that the file name has no significance despite the convention to name files after their content. It has been rewritten to make the relation between declarations, source files, and packages more clear. The example has been moved to a separate paragraph and expanded. The section on imports now explains the import syntax a bit more. The import examples have been expanded to include the example from the previous section, partially merged, and comments have been added. Fixes #473.
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 :)
The text was updated successfully, but these errors were encountered: