<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Nested namespace definition</title>
</head>
<body>

    <table><tbody>
        <tr><td>Document number:</td><td><i>N4026</i></td></tr>
        <tr><td>Date:</td><td><i>2014-05-23</i></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;</td></tr>
    </tbody></table>

    <h1>Nested namespace definition</h1>

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

    <ul>
        <li><a href="#introduction">II. Introduction</a></li>
        <li><a href="#motivation">III. Motivation</a></li>
        <li><a href="#impact">IV. Impact On the Standard</a></li>
        <li><a href="#issues">V. Open Issues</a></li>
        <li><a href="#specifications">VI. Technical Specifications</a></li>
    </ul>

</section>

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

    <p>The paper proposes allowing the use of a qualified name in a namespace definition to define several nested namespaces at once, for example:
    <pre><code>
    namespace A::B::C {
        //...
    }
    </code></pre>
    The code above would be equivalent to:
    <pre><code>
    namespace A {
        namespace B {
            namespace C {
                //...
            }
        }
    }
    </code></pre></p>

    <p>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>.</p>

</section>

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

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

    <p>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.</p>

    </section>

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

    <p>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).</p>

    </section>

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

    <p>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>).</p>

    </section>

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

    <p>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. 
    <pre><code>
    namespace A::B { typedef int I; }
    </code></pre>
    is equivalent to: 
    <pre><code>
    namespace A { namespace B { typedef int I; } }
    </code></pre>
    </blockquote></p>

    </section>

</section>

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

    <p>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.</p>

</section>

<section><h2 id="issues">V. Open Issues</h2>

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

    <p>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/n3957.html#113">EWG issue #113</a> may lift this limitation. In such case the proposal will have to take attributes into account, for example by stating that attributes, if any, apply only to the innermost namespace name and thus
    <pre><code>
    namespace A::B::C [[attr]] {
        //...
    }
    </code></pre>
    is equivalent to
    <pre><code>
    namespace A {
        namespace B {
            namespace C [[attr]] {
                //...
            }
        }
    }
    </code></pre></p>

    </section>

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

    <p>It is not yet clear to the author 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. Another possibility is to make inline qualified namespace definitions ill-formed.</p>

    </section>

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

    <p>By analogy, qualified names could also be allowed in namespace alias definitions, in which case
    <pre><code>
    using namespace A::B::C = X;
    </code></pre>
    would be equivalent to
    <pre><code>
    namespace A {
        namespace B {
            using namespace C = X;
        }
    }
    </code></pre>
    However, use cases for qualified namespace aliases seem to be infrequent (the author didn't find any in Boost for example) so they wouldn't be further considered if found useless or problematic for any reason.</p>

    </section>

</section>

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

    <p>Proposed wording will be provided at a later time.</p>

</section>

</body>
</html>
