This is a sample template to easily start a new DIP. DIPs can be fairly informal for now, but at least the leading metadata should be included, and a short abstract.

This proposal allows a module to be replaced with a package, without requiring changes to client code. It solves the problem of modules growing too large to be conveniently managed as one file, yet with an interface small enough. After the substitution users may continue using the same import statement to use the package, or may import only parts of it.

Changed: 20c20

Keeping track of improvement proposals is very hard and not well documented organized. Having a template (and a process) for such proposals can improve the situation significantly.

This is a "growing pains" kind of issue. Some modules in std (algorithm, datetime) have grown large, which makes it difficult to manage them as single files. Other libraries may be experiencing the same issue. This proposal allows breaking a module into a package without breaking client code that assumes the code is still in one module.

Changed: 24c24

A DIP is a D Improvement Proposal, a way propose changes to the language in a sightly more formal way than just throwing out the idea in the news group. A DIP should have an structure similar to this one, but nothing is set in stone, you can add or remove sections and/or metadata as long as the DIP is both clean and complete, but try to stick to this template as a bare minimum unless is really necessary to remove something.

* If the compiler sees a request for importing "foo.bar" and "foo/bar" is a directory, then automatically look for the file "foo/bar/package.d". If both "foo/bar.d" and "foo/bar/" exists, compilation halts with an error.

Changed: 26c26

A DIP should represent a problem the community wants to resolve and not just a specific resolution to a problem. This allows the DIP to be a central hub for any given problem. If a resolution is radically different from the current state of the DIP, an alternative DIP could be created as a sub page, e.g. under /DIPs/DIP1/Alternatives/Alt1?. The DIP should be created in its entirety such that it could replace the current DIP through simple copy and past.

* One nice detail of the design is that "package" is a keyword so the file "foo/bar/package.d" cannot be imported otherwise by mistake, which improves the robustness of the scheme.

Changed: 28,36c28

== Usage =

To start a new DIP you can go to Edit link and copy the source of this DIP, then go to DIP index and add a new item in the list. The DIP number should be one more than the last DIP in the index (for example, if the DIP1 is the last DIP, your DIP should be DIP2). The link in the index should have the form: <n>DIPx?, Title, Status, resume</n>. Where x is the DIP number, title is the DIP title and resume is a short description about the DIP.

Save the DIP index page and click on the ? at the side of the new link. Now you are editing the new DIP you just created, now paste the copied source text from this template and replace all the you need.

Remember to update the metadata at the start of the DIP, and keep it as a Draft at the beginning. When your DIP is done, you should announce it in the News Group for discussion, with a subject like this: new DIPx: title (where one more time x is the DIP number and title is the DIP title).

You should always put you DIPs in the Public Domain (or a similarly permissive license but use Public Domain unless you're very sure of what you're doing).

* The file "foo/bar/package.d" will be processed like a normal import, except the file is not allowed to use the "module" declaration. Instead, the file is assumed to have a "module foo.bar" declaration, i.e. it is interpreted as if it were the module "foo.bar".

Changed: 38c30

=== Recommendations =

* The file "foo/bar/package.d" will in all likelihood import whatever files in the package the developer decides.

Changed: 40,47c32

When writing a DIP, try not to express your opinion. DIPs should provide
facts and be as objective as possible. Even when that's pretty hard, you
can make the DIP look more objective by not using, for example, "I prefer
XXX because YYY". If YYY is an objective advantage, write that in a more
objective way, like "XXX can be a better option because YYY". Try to leave
non-technical personal preferences aside; "XXX can be a better option
because the syntax is nicer" is not good enough even when you don't say
"I prefer".

This proposal comes with an important lookup rules change. When looking up the symbol "foo.bar.baz", currently an exact match is needed. However. when looking up ".baz" or simply "baz", a flexible lookup is used that has many advantages (less verbose, hijacking detection etc). Therefore we think similar flexibility should be imparted to "foo.bar.baz", as follows:

Changed: 49,52c34

Try not to include half-baked ideas. If you are not sure about something,
leave it outside the DIP and write it on the NG announcement instead for
further discussion. The idea can be added to the DIP in the future when
it is in a better shape.

* If a qualified symbol "foo.bar.baz" appears in code, the compiler considers "foo.bar" a prefix that sets the starting point of the lookup, and then proceeds with looking up "baz" from that starting point. That means a program that imports std.algorithm may use "std.sort" for the symbol "std.algorithm.sort".

Changed: 54c36

==== Abstract =

* If more than one symbol is found, normal hijacking and collision rules apply.

Changed: 56,61c38

Make the abstract as descriptive as possible (while
keeping it brief). From an abstract you should be able to tell what the DIP is
about, you should introduce for every non-trivial concept a person should know
for understanding the DIP (or provide links if you can't briefly describe
those concepts in the abstract). Don't copy the title of the DIP to use it as
an abstract. Ideally an abstract should be a paragraph 5 to 10 lines long.

* This change in the lookup rule completes the proposal because it allows the code using "foo.bar.baz" to actually find "foo.bar.module13.baz", i.e. it supports transparently breaking modules into packages.

Changed: 63,74c40

==== Rationale =

Rationale should be complete. When the DIP tries to solve a problem, try to
describe that problem as detailed as possible. If you have links to the NG
describing the problem more deeply, used them. All the background information
is welcome.

==== NG Announcement =

When posting the DIP announcement to the NG, please copy the abstract, so
people can easily know what is it about and follow the link if they are
interested.

== Usage =

Added: 75a42

No particular usage notes beyond the above.

DIP16: Transparently substitute module with package

DIP:

16

Title:

Transparently substitute module with package

Version:

1

Status:

Draft

Created:

2012-03-30

Last Modified:

2012-03-30

Author:

Andrei Alexandrescu

Links:

Abstract

This proposal allows a module to be replaced with a package, without requiring changes to client code. It solves the problem of modules growing too large to be conveniently managed as one file, yet with an interface small enough. After the substitution users may continue using the same import statement to use the package, or may import only parts of it.

Rationale

This is a "growing pains" kind of issue. Some modules in std (algorithm, datetime) have grown large, which makes it difficult to manage them as single files. Other libraries may be experiencing the same issue. This proposal allows breaking a module into a package without breaking client code that assumes the code is still in one module.

Description

If the compiler sees a request for importing "foo.bar" and "foo/bar" is a directory, then automatically look for the file "foo/bar/package.d". If both "foo/bar.d" and "foo/bar/" exists, compilation halts with an error.

One nice detail of the design is that "package" is a keyword so the file "foo/bar/package.d" cannot be imported otherwise by mistake, which improves the robustness of the scheme.

The file "foo/bar/package.d" will be processed like a normal import, except the file is not allowed to use the "module" declaration. Instead, the file is assumed to have a "module foo.bar" declaration, i.e. it is interpreted as if it were the module "foo.bar".

The file "foo/bar/package.d" will in all likelihood import whatever files in the package the developer decides.

This proposal comes with an important lookup rules change. When looking up the symbol "foo.bar.baz", currently an exact match is needed. However. when looking up ".baz" or simply "baz", a flexible lookup is used that has many advantages (less verbose, hijacking detection etc). Therefore we think similar flexibility should be imparted to "foo.bar.baz", as follows:

If a qualified symbol "foo.bar.baz" appears in code, the compiler considers "foo.bar" a prefix that sets the starting point of the lookup, and then proceeds with looking up "baz" from that starting point. That means a program that imports std.algorithm may use "std.sort" for the symbol "std.algorithm.sort".

If more than one symbol is found, normal hijacking and collision rules apply.

This change in the lookup rule completes the proposal because it allows the code using "foo.bar.baz" to actually find "foo.bar.module13.baz", i.e. it supports transparently breaking modules into packages.