[ocaml-platform] on the need and design of OCaml namespaces

[Yaron Minsky]

On Wed, Feb 27, 2013 at 1:10 PM, Alain Frisch <alain.frisch at lexifi.com> wrote:
> On 02/27/2013 05:31 PM, Yaron Minsky wrote:
>>
>> Let me try to summarize the current situation about the argument
>> between Alain, Leo and myself.  I think Leo and I are roughly on the
>> same page, but I may be missing things.
>>
>> - MAKING LONG NAMES AVAILABLE.  Alain prefers to have unambiguous long
>>    names that are usable in a first class way.  I find this mildly
>>    distasteful, but would be OK with it as long as it was well hidden
>>    from the user by default.  Long names shouldn't show up by default
>>    in source files, error messages or documentation.  I view this as
>>    quite important for usability of namespaces.
>
>
> I don't understand how the user is supposed to interpret names in
> error messages or documentation without explicitly qualified names.
> It is ok, indeed, to assume that within the documentation of Core,
> references to its "List" module are written as "List", but then
> references to other List modules from other libraries would need to
> use their long names, right?  If another library, not part of Core,
> references types from Core_list, should we use simply "List" in its
> documentation?  Maybe, because Core is intended to be a real
> replacement of the stdlib, but this would perhaps not apply to other
> libraries, and it should certainly not be the default to always use
> short names for external references.

Garrigue's short-paths patch already goes a long way in this
direction, chopping opened modules from error messages.  Thus, if you
open Core.Std, a Hashtbl.t will show up as "Hashtbl.t", not
"Core.Std.Hashtbl.t".  We are generally quite happy with this outcome,
and it works well in our context.  We'd be happy with the same
behavior with namespaces.

For what it's worth, a Core.Std.List.t actually renders as "list",
since there is a type-equivalence there, and the short-paths patch
picks, well, the type with the shortest path to display.  We're very
happy with this behavior.

I would very much want this to be done for all libraries, not just
Core.  For example, we'd like the same behavior when we open
Async.Std, or, for that matter, My_special_purpose_library.Std.

> Being able to say for a given unit which name mapping is in scope is useful.
> This allows ocamldoc and error messages to use this mapping to use short
> names.  But there is also the request of being able to import a name mapping
> locally, for a sub-structure or locally in a function. While I understand
> this can be useful as a convenience for the programmer (example: a tool
> which needs to use locally the compiler-libs could import "ocaml.ns" in a
> restricted scope), I think it would create confusion to use those local
> mapping to shorten error messages.

The version of this in Garrigue's short-paths patch has been quite
good to us.  That experience leads me to think it's not too
problematic more generally.

>
>
>> - SOURCE-LEVEL OPENS.  Alain would prefer to have namespace
>>    manipulations restricted to the command line, and therefore the
>>    build system.  He thinks of namespaces as something that should be
>>    used pretty rarely (or at least, there should be very few
>>    namespaces), and it's therefore OK to push them to the outside.
>
>
> This does not completely reflect my position.  My initial proposal was about
> an "open namespace" statement which imports module aliases from a .ns file
> locally.  I've then restricted this proposal to only allow importing .ns
> file globally, and to do that on the command-line in order to make the use
> of "stdlib replacements" as transparent as the official stdlib for
> programmers.  I thought this would be a good thing for Core.  Now Leo and
> you have convinced me that (i) being able to import .ns file locally is also
> quite useful; (ii) allowing to specify global .ns file on the command-line
> is neither necessary nor a good idea.  So let me retract my simplified
> proposal and stick to the original one.

Great!

> That said, I still believe that one needs a way to tell for instance
> ocamldoc which .ns files to use to shorten references when generating the
> documentation for a given module.  And I believe it would be extremely
> confusing for users to allow to use different .ns files on the same page,
> depending on "open .ns" statements in the .mli file.  So either ocamldoc
> should get this information from the command-line, or it should find in the
> source code itself.  I don't really care, as long as this is restricted to a
> global choice for a given unit.

I agree with this.

>> - NAMESPACES WITH VALUES.  I have argued for allowing the opening of a
>>    namespace to also implicitly open some modules, this essentially
>>    adding values to the search path in addition to modules.  I would be
>>    sad to lose this feature, but I don't think it's absolutely
>>    essential.
>
>
> I've a preference for keeping independent notions as separate in the
> language design even if they are commonly used together.  But I agree, this
> is a non fundamental issue.

I see your point about independence, but in my mind, the difference
between managing the namespace of modules and managing the namespace
of values is of more interest to compiler implementors than language
users.  These are really quite close to the same concept, and does
comparatively little semantic violence.

y