[swift-evolution] Yet Another Take on Swift Sub-modules

[Xiaodi Wu]

Left unsaid from my earlier message was that I wonder why an explicit
submodule declaration would be necessary at all if you commit to the
principles laid out by Karim.
On Sun, Mar 5, 2017 at 13:33 Matthew Johnson <matthew at anandabits.com> wrote:

> On Mar 5, 2017, at 1:29 PM, Karim Nassar via swift-evolution <
> swift-evolution at swift.org> wrote:
>
>
>
> On Mar 5, 2017, at 2:06 PM, Xiaodi Wu <xiaodi.wu at gmail.com> wrote:
>
> Punycode would readily cover your first issue about legal identifier
> characters.
>
>
> Well, it would cover… I’m not sure if “readily” would be the right word.
>
> If I have a sub-module I want to call `Bücher`, and I have to name the
> directory `Bcher-kva`, what do I use to refer to the sub-module in my code?
> It’s not at all readable, nor is it discoverable to a 3rd party who if they
> don’t “know” about Punycode, have no reason to associate the `Bücher`
> sub-module with the `Bcher-kva` directory.
>
> Not that’s a show-stopper, mind. I wouldn’t mind further exploring the
> directory-name + “extension" approach.
>
>
> If we explore this I think it needs to be as a form of “syntactic sugar”
> only.  We still need a place to write an explicit submodule declaration.
>
>
> —Karim
>
> As to the second, having enumerated the essential properties of a Foo,
> what "growth" are you envisioning?
> On Sun, Mar 5, 2017 at 12:51 Karim Nassar via swift-evolution <
> swift-evolution at swift.org> wrote:
>
>
> On Mar 5, 2017, at 10:10 AM, Rien <Rien at Balancingrock.nl> wrote:
>
>
> On 05 Mar 2017, at 15:52, Karim Nassar via swift-evolution <
> swift-evolution at swift.org> wrote:
>
>
> On Mar 4, 2017, at 2:54 PM, Matthew Johnson <matthew at anandabits.com>
> wrote:
>
>
> On Mar 4, 2017, at 9:56 AM, Karim Nassar <karim at karimnassar.com> wrote:
>
>
> On Mar 3, 2017, at 5:21 PM, Matthew Johnson <matthew at anandabits.com>
> wrote:
>
>
> On Mar 3, 2017, at 9:24 AM, Karim Nassar via swift-evolution <
> swift-evolution at swift.org> wrote:
>
> Changes that *are* necessary are:
>
> * Change the spelling of `internal` to `module` (making `module` the new
> default)
> * Introduce a new modifier `internal` to mean "Internal to the current
> sub-module and its child-sub-modules”
>
>
> Can you give concrete examples of use cases where a descendent submodule
> needs access to symbols declared by an ancestor?  I gave some thought to
> this when drafting my proposal and came to the conclusion that this runs
> against the grain of layering and is likely to be a bad idea in practice.
> If there are use cases I didn’t consider I am very interested in learning
> about them.
>
>
> On further reflection and examination of my notes, I think you’re right,
> and that the `internal` encapsulation should be purely horizontal. Will
> adjust to reflect that.
>
> ### Making a Sub-module
>
> To create a sub-module within a Module (or sub-module) is simple: The
> author creates a directory, and places a "sub-module declaration file"
> within the directory:
>
> ```
> //  __submodule.swift
>
>
> Why the double underscore prefix?  To make it sort to the top in a file
> browser?
>
> Is this file allowed to have any Swift code?  Or is it limited to
> submodule-related declarations only?  If the latter, why not use an
> extension such as `.submodule` or `.swiftmodule` to differentiate it from
> ordinary Swift files and allow the submodule to be named by the name of
> this file?
>
>
> So, my reasoning was that by requiring a specific standard name for the
> declaration file, we guarantee that any directory can only describe one
> submodule. Prefixing the proposed name with underscores was simply a way of
> preventing naming collision with potential “real code” files (and yes, as a
> side-effect alpha-floating it to the top). Since the `submodule`
> declaration might expand to include statements & configuration about the
> sub-module, I see no reason to prohibit Swift code from existing in that
> sub-module declaration file… Disallowing/controlling that seems to be a
> style/linter concern.
>
> However, as I mentioned above, all the specific spellings (except
> `internal`)  for the different concepts in this proposal are straw-men
> awaiting input. I’d say the addition of a new type of file extension raises
> some concerns for me, but there’s already been a lot of push back on the
> general idea of using filesystem structures to organize sub-modules, so the
> whole idea may be moot.
>
>
> I’ve actually been starting to come around to the idea of using the file
> system.  Not so much because I really like it, but because I have been
> considering further some of the drawbacks of other approaches.
>
> One big reason is that a submodule should form a scope and scopes should
> consist of code that is physically adjacent.  In practice this means it
> should reside in close proximity in the file system.  Allowing any file in
> a project to be a part of any submodule partly defeats the purpose of using
> them to structure a project internally.  If we’re going to be organizing
> the files in a submodule physically anyway maybe we should just take
> advantage of that fact and prevent a stray file in a distant part of the
> file system from being part of the submodule.
>
> The second reason is that there is a big problem with placing a simple
> `submodule Foo` declaration at the top of each file in a submodule.  We all
> make typos from time to time.  This method makes it too easy to
> accidentally type `submodule Fooo` and end up in a submodule you didn’t
> intend.  This mistake would likely be caught relatively quickly but it
> seems silly to have a system subject to this kind of mistake.  This means
> we would end arbitrarily placing the declaration in one file and saying
> `extends submodule Foo` in the rest of the files.  Your design avoids the
> need to arbitrarily choose where to place the declaration and avoids the
> need for a declaration in the rest of the files.
>
>
> I’m not dead-set on this approach, but as you say, it solves a *lot* of
> problems that other approaches introduce. I do recognize the reasonableness
> of the main argument against, that file location shouldn’t have such a
> dramatic affect on behavior… *but* the fact is (whether by convention or
> expediency) we already *do* have filesystem location dependencies on our
> code projects…
>
> * One can’t willy-nilly move files around the disk and expect a project to
> build… if you move it somewhere the compiler doesn’t know to look for it,
> you’re going to break things
> * One can’t just move a file out of your SCM repo root, or you’ll “lose”
> the file
>
>
> True, but if other files do not refer to the lost file, you don’t even
> know for which file to look.
> (imo this is already a weak point in swift, but this approach to
> submodules would make it -much?- worse)
>
> If you were to include filenames in the “submodule declaration file” at
> least this omission in swift would be partly covered, and you would not
> need to move the other files into special places. (You could though)
>
>
> But isn’t this exactly the same case if you’re using Swift without an IDE?
> It’s true that Xcode keeps track of files in your project, and there’s no
> reason it couldn’t also keep track of files in a submodule (in fact it
> would… it just might not know they belong in the sub-module without some
> work from the Xcode dev team).
>
> But as a thought-experiment, here’s how I’m thinking of this problem:
>
> Swift (as a language) has established that a file *is* a unit of code. Not
> the only one of course, but it is one, as evidenced by access controls
> (fileprivate, Swift2 private) which bound on the file.
>
> I (and many others) want to be able to describe another unit of code
> larger than a file and smaller than a Module to help organize the
> file-units we have which go together within a Module, but which shouldn’t
> (for various reasons) describe a complete Module in and of themselves.
>
> For the moment—though we actually propose to call this unit a
> sub-module—we'll call this new unit a Foo. Let's describe properties of a
> Foo:
>
> * A Foo should serve to organize one or more File code units by:
>   - ensuring a File (the code-unit) may belong to one and only one Foo
>   - making clear (with or without an IDE) to which Foo a given file might
> belong
> * A Foo should have a unique name
> * A Foo should be able to nest under another Foo, and the name of that
> nesting should be clear & unique
> * A Foo should be able to be easily created, split, and merged as the
> codebase evolves
> * A Foo should be able to be moved, copied, and SCMed as a unit, without
> reference to anything outside the Foo
>
> Having now described the critical properties of this new unit called “Foo”
> have we not also described a filesystem directory?
>
> Naturally, we don’t want *all* directories to become Foos (that would be
> overly restrictive to authors, and backwards-incompatible), so we need a
> way to distinguish a normal directory from one that is acting as a Foo. I
> originally proposed a special “sub-module declaration file”, but there may
> be other ways. For example, we might establish that a directory whose name
> matches `[SubModuleName].swift-sub-module` becomes a sub-module of
> designated name, however this can cause problems due to the disjoint sets
> of “Legal Filesystem Directory Characters” and “Legal Swift Identifier
> Characters”. It also doesn’t give us a place to “grow” the declaration in
> the future if we choose to add additional properties to the sub-module
> declaration.
>
>
> —Karim
>
>
>
>
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
>
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20170305/dae88f51/attachment.html>