<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Nested namespace definition (revision 2)</title>
    <style>
        ins { background-color: LightGreen; }
        del { background-color: LightPink; }
        pre { font: inherit; }
    </style>
</head>
<body>

    <table><tbody>
        <tr><td>Document number:</td><td>N4230</td></tr>
        <tr><td>Date:</td><td>2014-10-10</td></tr>
        <tr><td>Project:</td><td>Programming Language C++, Evolution Working Group</td></tr>
        <tr><td>Reply-to:</td><td>Robert Kawulak &lt;Robert Kawulak at gmail dot com&gt;, Andrew Tomazos &lt;Andrew Tomazos at gmail dot com&gt;</td></tr>
    </tbody></table>

    <h1>Nested namespace definition (revision 2)</h1>

<section><h2 id="contents">I. Table of Contents</h2>

    <ul>
        <li><a href="#revisions">II. Revision History</a></li>
        <li><a href="#introduction">III. Introduction</a></li>
        <li><a href="#motivation">IV. Motivation</a></li>
        <li><a href="#impact">V. Impact On the Standard</a></li>
        <li><a href="#design">VI. Design Decisions</a></li>
        <li><a href="#specifications">VII. Technical Specifications</a></li>
    </ul>

</section>

<section><h2 id="revisions">II. Revision History</h2>

    <em>Note:</em> this document (revision 2) is based on <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4026.html">N4026</a> (the initial proposal) and partially incorporates <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4116.pdf">N4116</a> (revision 1), which was not based on the original document.

    <h3>Changes from <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4026.html">N4026</a>:</h3>

    <ul>
        <li>Reworded <cite>Open Issues</cite> into <a href="#design"><cite>Design Decisions</cite></a> following the feedback from Rapperswil.</li>
        <li>Incorporated and modified wording for <a href="#wording-feature"><cite>Core Feature</cite></a> from <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4116.pdf">N4116</a>.</li>
        <li>Added wording for <a href="#wording-usage"><cite>Usage in the Standard</cite></a>.</li>
    </ul>

</section>

<section><h2 id="introduction">III. Introduction</h2>

    The paper proposes allowing the use of a qualified name in a namespace definition to define several nested namespaces at once, for example:

    <blockquote>
<pre><code>namespace A::B::C {
    //…
}</code></pre>
    </blockquote>

    The code above would be equivalent to:

    <blockquote>
<pre><code>namespace A {
    namespace B {
        namespace C {
            //…
        }
    }
}</code></pre>
    </blockquote>

    The feature was already proposed by Jon Jagger in 2003 in the paper <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1524.htm">N1524 <cite>Nested Namespace Definition Proposal</cite></a>, but it has been listed in <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2869.html">N2869 <cite>State of C++ Evolution (Post San Francisco 2008)</cite></a> under <q>Not ready for C++0x, but open to resubmit in future</q>.

</section>

<section><h2 id="motivation">IV. Motivation</h2>

    <section><h3 id="demand">Programmers' demand</h3>

    There is clearly a need for a more concise way of defining nested namespaces than what the language offers today. The feature is asked for over and over by C++ users; see for example a few of the top web search results for a related query:

    <ul>
        <li><a href="https://groups.google.com/a/isocpp.org/d/topic/std-proposals/o7U08Z_7EgI/discussion">ISO C++ Standard – Future Proposals forum: <cite>nested namespace declaration</cite></a></li>
        <li><a href="https://groups.google.com/a/isocpp.org/d/topic/std-proposals/HMUt_-cb4Wg/discussion">ISO C++ Standard – Future Proposals forum: <cite>Namespaces-related open questions</cite></a></li>
        <li><a href="http://stackoverflow.com/q/11358425">Stack Overflow: <cite>Is there a better way to express nested namespaces in C++ within the header</cite></a></li>
        <li><a href="http://stackoverflow.com/q/3603461">Stack Overflow: <cite>Is there a specific reason nested namespace declarations are not allowed in C++?</cite></a></li>
        <li><a href="http://stackoverflow.com/q/3589204">Stack Overflow: <cite>Multiple namespace declaration in C++</cite></a></li>
        <li><a href="http://visualstudio.uservoice.com/forums/121579/suggestions/2286601">Visual Studio UserVoice: <cite>Nested namespace declarations</cite></a> (Note that it is currently the 20<sup>th</sup> top voted idea out of 238 for C++.)</li>
    </ul>

    Quite possibly some of the users asking for this feature are novices/newcomers from other languages who used this syntax intuitively and found that their compiler doesn't accept it. This might indicate that the new syntax would not only mean saving some typing to experienced programmers, but it would also mean one confusion less to C++ learners.

    </section>

    <section><h3 id="prevalence">Prevalence</h3>

    It is not uncommon to find many deeply nested namespaces in large projects. For example, a search using the regular expression pattern <code>(namespace\s+\w+\s*\{\s*){3,}</code> to find nested namespace definitions at least 3 levels deep in the include directory of <a href="http://www.boost.org/">Boost libraries</a> yielded 3758 matches and the greatest nesting level found this way was 7 (4 matches).

    </section>

    <section><h3 id="existing-other">Existing practice in other languages</h3>

    An <a href="http://msdn.microsoft.com/en-us/library/dfb3cx8s.aspx#code-snippet-7">analogous syntax</a> is found and heavily used in the C# programming language. Some other languages do not even allow for nesting of namespace definitions but only for providing a hierarchical namespace specification in a single declaration (e.g. <a href="http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1">Java</a> or <a href="http://www.php.net/manual/en/language.namespaces.nested.php">PHP</a>).

    </section>

    <section><h3 id="existing-cpp">Existing practice in C++</h3>

    The author is not aware of any C++ compiler supporting this feature; however <a href="http://www.lazycplusplus.com/">Lzz</a>, <q>a tool that automates many onerous C++ programming tasks</q>, supports it – from the tool's <a href="http://www.lazycplusplus.com/doc.html#support">documentation</a>:

    <blockquote>
    The name of a named namespace may be qualified. 
        <blockquote>
        <code>namespace A::B { typedef int I; }</code>
        </blockquote>
    is equivalent to: 
        <blockquote>
        <code>namespace A { namespace B { typedef int I; } }</code>
        </blockquote>
    </blockquote>

    </section>

</section>

<section><h2 id="impact">V. Impact On the Standard</h2>

    The proposal describes a pure language extension which is a non-breaking change – code that was previously ill-formed now would have well-defined semantics.

</section>

<section><h2 id="design">VI. Design Decisions</h2>

    This section describes some issues related to the proposed feature and corresponding decisions based on the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4101.html#126">guidance from the EWG</a> given at the Rapperswil meeting.

    <section><h3 id="attributes">Attributes</h3>

    Currently, the C++ Standard doesn't allow for specification of attributes for namespaces, but a resolution to the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4101.html#113">EWG issue #113</a> may lift this limitation. This proposal does not take attributes into account, but support for attributes can be added by a later proposal if found desirable.

    </section>

    <section><h3 id="inline">Inline namespaces</h3>

    It is not clear what is the best way to deal with inline namespaces. One possibility is that only the innermost namespace is defined inline, another one is that all the specified namespaces are inline. In either case the semantics seem to be potentially confusing, thus this proposal does not allow for inline qualified namespace definitions at all.

    </section>

    <section><h3 id="aliases">Namespace aliases</h3>

    By analogy, qualified names could also be allowed in namespace alias definitions, e.g.

    <blockquote>
    <code>using namespace A::B::C = X;</code>
    </blockquote>

    However, use cases for qualified namespace aliases seem to be infrequent (the author didn't find any in Boost for example) so they aren't considered by this proposal.

    </section>

</section>

<section><h2 id="specifications">VII. Technical Specifications</h2>

    The proposed wording defines the core feature and makes use of it throughout the Standard text where applicable. It is relative to the <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3797.pdf">N3797</a> working draft.

    <section><h3 id="wording-feature">Core Feature</h3>

    <ul>

        <li>Change § 7.3.1 p. 1 [namespace.def] and § A.6 [gram.dcl] as follows:
        <blockquote>
<pre>…
<var>namespace-name</var>:
    <var>original-namespace-name</var>
    <var>namespace-alias</var>
<var>original-namespace-name</var>:
    <var>identifier</var>
<var>namespace-definition</var>:
    <var>named-namespace-definition</var>
    <var>unnamed-namespace-definition</var>
    <ins><var>nested-namespace-definition</var></ins>
<var>named-namespace-definition</var>:
    <var>original-namespace-definition</var>
    <var>extension-namespace-definition</var>
<var>original-namespace-definition</var>:
    <code>inline</code><sub><var>opt</var></sub> <code>namespace</code> <var>identifier</var> <code>{</code> <var>namespace-body</var> <code>}</code>
<var>extension-namespace-definition</var>:
    <code>inline</code><sub><var>opt</var></sub> <code>namespace</code> <var>original-namespace-name</var> <code>{</code> <var>namespace-body</var> <code>}</code>
<var>unnamed-namespace-definition</var>:
    <code>inline</code><sub><var>opt</var></sub> <code>namespace</code> <code>{</code> <var>namespace-body</var> <code>}</code>
<ins><var>nested-namespace-definition</var>:</ins>
    <ins><code>namespace</code> <var>enclosing-namespace-specifier</var> <code>::</code> <var>identifier</var> <code>{</code> <var>namespace-body</var> <code>}</code></ins>
<ins><var>enclosing-namespace-specifier</var>:</ins>
    <ins><var>identifier</var></ins>
    <ins><var>enclosing-namespace-specifier</var> <code>::</code> <var>identifier</var></ins>
<var>namespace-body</var>:
    <var>declaration-seq</var><sub><var>opt</var></sub>
…</pre>
        </blockquote>
        </li>

        <li>Add new paragraph 10 to § 7.3.1 [namespace.def]:
        <blockquote>
        <ins>A <var>nested-namespace-definition</var> with an <var>enclosing-namespace-specifier</var> <code>E</code>, <var>identifier</var> <code>I</code> and <var>namespace-body</var> <code>B</code> is equivalent to</ins>
            <blockquote>
            <code><ins>namespace E { namespace I { B } }</ins></code>
            </blockquote>
        <ins>[<i>Example:</i></ins>
            <blockquote>
<pre><code><ins>namespace A::B::C {
    int i;
}</ins></code></pre>
            </blockquote>
        <ins>The above has the same effect as:</ins>
            <blockquote>
<pre><code><ins>namespace A {
    namespace B {
        namespace C {
            int i;
        }
    }
}</ins></code></pre>
            </blockquote>
        <ins><i>—end example</i>]</ins>
        </blockquote>
        </li>

    </ul>

    </section>

    <section><h3 id="wording-usage">Usage in the Standard</h3>

    <ul>

        <li>Change § 20.9.9.1.4 [func.bind.place] as follows:
        <blockquote>
<pre><code>namespace std<ins>::placeholders</ins> {
<del>    namespace placeholders {</del>
    …
<del>    }</del>
}</code></pre>
        </blockquote>
        </li>

        <li>Change § 28.5.1 [re.synopt] as follows:
        <blockquote>
<pre><code>namespace std<ins>::regex_constants</ins> {
<del>    namespace regex_constants {</del>
    …
<del>    }</del>
}</code></pre>
        </blockquote>
        </li>

        <li>Change § 28.5.2 [re.matchflag] as follows:
        <blockquote>
<pre><code>namespace std<ins>::regex_constants</ins> {
<del>    namespace regex_constants {</del>
    …
<del>    }</del>
}</code></pre>
        </blockquote>
        </li>

        <li>Change § 28.5.3 [re.err] as follows:
        <blockquote>
<pre><code>namespace std<ins>::regex_constants</ins> {
<del>    namespace regex_constants {</del>
    …
<del>    }</del>
}</code></pre>
        </blockquote>
        </li>

        <li>Change § 30.3.2 [thread.thread.this] as follows:
        <blockquote>
<pre><code>namespace std<ins>::this_thread</ins> {
<del>    namespace this_thread {</del>
    …
<del>    }</del>
}</code></pre>
        </blockquote>
        </li>

    </ul>

    </section>

</section>

</body>
</html>
