Support '_' as a magic identifier for certain declarations

Allowed for method-local bindings and index variables.
Method-local bindings named '_' are not added to scope
Index variables named '_' do not get a parameter created for them

Author: lwaern-intel

RELEASENOTES-1.4.docu

@@ -533,4 +533,27 @@
       _ = throwing_method();
       (_, x, _) = method_with_multiple_return_values();
       </pre></add-note></build-id>
+  <build-id value="next"><add-note> '_' can no longer be used as the name for
+      arbitrary declarations. Instead, it is now only permitted in particular
+      contexts, and in these contexts, '_' will affect the declaration in a way
+      suitable for when the declaration is <em>unused</em>.
+      These contexts are:
+      <dl>
+        <dt>Method-local bindings (e.g. variables and input parameters)</dt>
+            <dd>When a method-local binding is given the name '_', it will not
+                be added to scope. This is useful for e.g. unused method
+                parameters.</dd>
+        <dt>Index variables for object arrays</dt>
+            <dd>When '_' is specified as an index variable, a parameter will
+                not be created for it, meaning it cannot conflict with any
+                other definition, and it cannot be referenced in the code in
+                order to get the value of the index in question.
+                It also isn't considered to conflict with any other definition
+                that gives the index variable a different name.
+                This is useful when defining an object array specification which
+                does not depend on the index.</dd>
+      </dl>
+      Note that as a consequence of these semantics, any reference to
+      '<tt>_</tt>' in code will <em>always</em> resolve to the discard
+      reference.<add-note></build-id>
 </rn>

doc/1.4/language.md

@@ -78,9 +78,18 @@ Identifiers
 
 Identifiers in DML are defined as in C; an identifier may begin
 with a letter or underscore, followed by any number of letters,
-numbers, or underscores. Identifiers that begin with an underscore (`_`)
-are reserved by the DML language and standard library and should not
-be used.
+numbers, or underscores.
+
+<a id="discard-identifier"/>
+Identifiers that begin with an underscore (`_`) are reserved by the DML language
+and standard library and should not be used, with the exception of the single
+underscore `_`; this is considered to be the *discard identifier*, and is only
+permitted as the name of a declaration in specific contexts, where it gives the
+declaration special semantics. Currently, these contexts are:
+* Method-local bindings, e.g. [local variables](#local-statements) &mdash;
+see that section for more information.
+* Index parameters for object arrays. See the documentation for the
+  [`object` template] for more information.
 
 </dd><dt>
 
@@ -3098,6 +3107,29 @@ method m() -> (bool, int) {
 local (bool a, int i) = m();
 ```
 
+
+"\_" may be used as an identifier for local variables, as well as other
+method-local bindings such as the method parameters, and the bound identifier
+in `foreach`/`#foreach`/`#select` statements, and message component paramters of
+[hook-bound after statements](#hook-bound-after-statements). Any method-local
+binding named "\_" *will not be added to scope.* This is useful for when
+a method parameter is unused, or if you perform a method call where only a
+subset of returned values are of interest:
+```
+local (bool a, int _) = m();
+// No conflicts since "_" is not added to scope
+local (bool a, int _, float _) = returns_three_vals();
+```
+
+An alternative to this pattern is to leverage the
+[discard reference](#discard-reference)
+```
+local bool a;
+(a, _, _) = returns_three_vals();
+```
+... which does not require you to specify the types of the discarded values,
+but requires multiple lines.
+
 ### Session Statements
 <pre>
 session <em>type</em> <em>identifier</em> [= <em>initializer</em>];
@@ -3809,6 +3841,7 @@ independent method callback(int i, void *aux) {
 ```
 
 ### The Discard Reference (`_`)
+<a id="discard-reference"/>
 ```
 _
 ```
@@ -3817,10 +3850,6 @@ The discard reference *`_`* is an expression without any run-time representation
 that may be used as the target of an assignment in order to explicitly discard
 the result of an evaluated expression or return value of a method call.
 
-For backwards compatibility reasons, `_` is not a keyword, but instead behaves
-more closely as a global identifier. What this means is that declared
-identifiers (e.g. local variables) are allowed to shadow it by being named `_`.
-
 Example usage:
 ```
 // Evaluate an expression and explicitly discard its result.
@@ -3834,6 +3863,9 @@ _ = throwing_method();
 (_, x, _) = method_with_multiple_return_values();
 ```
 
+The discard reference is related to the [discard
+identifier](#discard-identifier), and have some use-cases in common.
+
 ### New Expressions
 
 <pre>

lib/1.4/dml-builtins.dml

@@ -431,11 +431,23 @@ which cannot be overridden:
   single field inside a register array, the value is the empty list.
 
 * Each array has an *individual index parameter*, to make it possible
-  to refer to both inner and outer indexes when arrays are nested
+  to refer to both inner and outer indices when arrays are nested
   (cf. the `indices` parameter, above). The parameter name is
   specified in the array declaration; for instance, the declaration
   `register regs[i < 4][j < 11];` defines two index parameters, `i` and `j`.
   In this case, the `indices` parameter is `[i, j]`.
+  "\_" is also allowed as the name of one or more index parameters. If
+  used, then it *won't* result in corresponding parameter definitions for those
+  indices; in other words, if an index variable is named "\_", then it can't be
+  accessed by that name (however, the `indices` parameter is unaffected and
+  could be used instead.) It's also allowed to have an object array
+  specification name an index parameter "\_" even if some other object array
+  specification uses a different name (which *will* be given a corresponding
+  parameter definition.) This is useful if a specific object array
+  specification doesn't need to make use of some particular indices; or if the
+  specification needs to support that the naming of the index variable may vary
+  depending on what other specifications of the same object array are present
+  in the device model.
 
 The `object` template provides the non-overridable method `cancel_after()`,
 which cancels all pending events posted using `after` which are associated with

py/dml/c_backend.py

@@ -720,7 +720,15 @@ def wrap_method(meth, wrapper_name, indices=()):
     is a port object
     """
 
-    inparams = [t.declaration(p) for p, t in meth.inp]
+    inp = list(meth.inp)
+    if meth.astcode.site.dml_version() != (1, 2):
+        discarded = 0
+        for (i, (n, t)) in enumerate(inp):
+            if n == '_':
+                inp[i] = (f'_unused_{discarded}', t)
+                discarded += 1
+    inparams = [t.declaration(p) + ' UNUSED'*(p.startswith('_unused_'))
+                for p, t in inp]
     if not meth.outp:
         retvar = None
         rettype = TVoid()

py/dml/codegen.py

@@ -952,7 +952,7 @@ def declarations(scope):
         if sym.stmt:
             continue
         decl = sym_declaration(sym)
-        if decl:
+        if not decl.is_empty:
             decls.append(decl)
 
     return decls
@@ -2036,19 +2036,20 @@ def mk_sym(name, typ, mkunique=not dml.globals.debuggable):
                                                    tgts, location, scope)
         if method_invocation is not None and stmt.site.dml_version != (1, 2):
             for sym in syms_to_add:
-                scope.add(sym)
+                if sym.name != '_':
+                    scope.add(sym)
             stmts.extend(sym_declaration(sym) for sym in tgt_syms)
             stmts.append(method_invocation)
-            stmts.extend(sym_declaration(sym)
-                         for sym in late_declared_syms)
+            stmts.extend(sym_declaration(sym) for sym in late_declared_syms)
         else:
             if len(tgts) != 1:
                 report(ERETLVALS(stmt.site, 1, len(tgts)))
             else:
                 sym = syms_to_add[0]
                 sym.init = ExpressionInitializer(
                     codegen_expression(inits[0].args[0], location, scope))
-                scope.add(sym)
+                if not (sym.name == '_' and stmt.site.dml_version() != (1, 2)):
+                    scope.add(sym)
                 stmts.append(sym_declaration(sym))
     else:
         # Initializer evaluation and variable declarations are done in separate
@@ -2057,9 +2058,13 @@ def mk_sym(name, typ, mkunique=not dml.globals.debuggable):
         inits = [get_initializer(stmt.site, typ, init, location, scope)
                  for ((_, typ), init) in zip(decls, inits)]
         for ((name, typ), init) in zip(decls, inits):
-            sym = scope.add_variable(
-                name, type = typ, site = stmt.site, init = init, stmt = True,
-                make_unique=not dml.globals.debuggable)
+            if not (name == '_' and stmt.site.dml_version() != (1, 2)):
+                sym = scope.add_variable(
+                    name, type = typ, site = stmt.site, init = init,
+                    stmt = True, make_unique=not dml.globals.debuggable)
+            else:
+                sym = mk_sym(name, typ)
+
             stmts.append(sym_declaration(sym))
 
     return stmts
@@ -2401,7 +2406,7 @@ def stmt_assign(stmt, location, scope):
 
         lscope = Symtab(scope)
         sym = lscope.add_variable(
-            'tmp', type=init_typ, site=init.site, init=init,
+            '_tmp', type=init_typ, site=init.site, init=init,
             stmt=True)
         init_expr = mkLocalVariable(init.site, sym)
         stmts = [sym_declaration(sym)]
@@ -2437,7 +2442,7 @@ def stmt_assign(stmt, location, scope):
             else:
                 init = eval_initializer(site, tgt.ctype(), src_ast, location,
                                         scope, False)
-                name = 'tmp%d' % (i,)
+                name = '_tmp%d' % (i,)
                 sym = lscope.add_variable(
                         name, type=tgt.ctype(), site=tgt.site, init=init,
                         stmt=True)
@@ -2930,6 +2935,9 @@ def stmt_afteronhook(stmt, location, scope):
 
     msg_comp_params = {}
     for (idx, (mcp_site, mcp_name)) in enumerate(msg_comp_param_asts):
+        if mcp_name == '_':
+            continue
+
         if mcp_name in msg_comp_params:
             raise EDVAR(mcp_site, msg_comp_params[mcp_name][1],
                         mcp_name)
@@ -3079,7 +3087,8 @@ def stmt_select(stmt, location, scope):
             clauses = []
             for it in l:
                 condscope = Symtab(scope)
-                condscope.add(ExpressionSymbol(itername, it, stmt.site))
+                if not (itername == '_' and stmt.site.dml_version() != (1, 2)):
+                    condscope.add(ExpressionSymbol(itername, it, stmt.site))
                 cond = as_bool(codegen_expression(
                     cond_ast, location, condscope))
                 if cond.constant and not cond.value:
@@ -3115,9 +3124,10 @@ def foreach_each_in(site, itername, trait, each_in,
                     body_ast, location, scope):
     inner_scope = Symtab(scope)
     trait_type = TTrait(trait)
-    inner_scope.add_variable(
-        itername, type=trait_type, site=site,
-        init=ForeachSequence.itervar_initializer(site, trait))
+    if itername != '_':
+        inner_scope.add_variable(
+            itername, type=trait_type, site=site,
+            init=ForeachSequence.itervar_initializer(site, trait))
     context = GotoLoopContext()
     with context:
         inner_body = mkCompound(site, declarations(inner_scope)
@@ -3198,8 +3208,9 @@ def foreach_constant_list(site, itername, lst, statement, location, scope):
                                    TInt(32, True))
                              for dim in range(len(items.dimsizes)))
             loopscope = Symtab(scope)
-            loopscope.add(ExpressionSymbol(
-                itername, items.expr(loopvars), site))
+            if not (itername == '_' and site.dml_version() != (1, 2)):
+                loopscope.add(ExpressionSymbol(
+                    itername, items.expr(loopvars), site))
             stmt = codegen_statement(statement, location, loopscope)
 
             if stmt.is_empty:
@@ -3584,6 +3595,7 @@ def codegen_inline(site, meth_node, indices, inargs, outargs,
             # call is safe.
             return codegen_call(site, meth_node, indices,
                                 inargs, outargs)
+        pre = []
         for (arg, (parmname, parmtype), argno) in zip(inargs, meth_node.inp,
                                                       list(range(len(inargs)))):
             # Create an alias
@@ -3604,7 +3616,12 @@ def codegen_inline(site, meth_node, indices, inargs, outargs,
                     raise ECONSTP(site, parmname, "method call")
                 arg = coerce_if_eint(arg)
 
-            if inhibit_copyin or undefined(arg):
+            if (parmname == '_'
+                and meth_node.astcode.site.dml_version() != (1, 2)):
+                if not arg.constant:
+                    pre.append(mkExpressionStatement(arg.site, arg,
+                                                     explicit_discard=True))
+            elif inhibit_copyin or undefined(arg):
                 param_scope.add(ExpressionSymbol(parmname, arg, arg.site))
             elif arg.constant and (
                     parmtype is None
@@ -3661,13 +3678,13 @@ def codegen_inline(site, meth_node, indices, inargs, outargs,
             exit_handler = GotoExit_dml14(outargs)
             with exit_handler:
                 code = codegen_statements(subs, location, param_scope)
-            decls = declarations(param_scope)
+            pre.extend(declarations(param_scope))
             post = ([mkLabel(site, exit_handler.label)]
                     if exit_handler.used else [])
-            body = mkCompound(site, decls + code, rbrace_site)
+            body = mkCompound(site, pre + code, rbrace_site)
             if meth_node.outp and body.control_flow().fallthrough:
                 report(ENORET(meth_node.astcode.site))
-            return mkInlinedMethod(site, meth_node, decls, code, post)
+            return mkInlinedMethod(site, meth_node, pre, code, post)
 
 def c_rettype(outp, throws):
     if throws:
@@ -3725,14 +3742,24 @@ def __init__(self, method, inp, outp, throws, independent, startup,
 
         # rettype is the return type of the C function
         self.rettype = c_rettype(outp, throws)
+        cparams = list(cparams)
+
+        if method.astcode.site.dml_version() != (1, 2):
+            discarded = 0
+            for (i, (n, t)) in enumerate(cparams):
+                if n == '_':
+                    cparams[i] = (f'_unused_{discarded}', t)
+                    discarded += 1
+
         self.cparams = c_inargs(
-            implicit_params(method) + list(cparams), outp, throws)
+            implicit_params(method) + cparams, outp, throws)
 
     @property
     def prototype(self):
         return self.rettype.declaration(
             "%s(%s)" % (self.get_cname(),
                         ", ".join([t.declaration(n)
+                                   + ' UNUSED'*n.startswith('_unused_')
                                    for (n, t) in self.cparams])))
 
     def cfunc_expr(self, site):
@@ -3826,7 +3853,9 @@ def codegen_method_func(func):
         if dml.globals.dml_version == (1, 2) and (
                 compat.dml12_misc not in dml.globals.enabled_compat):
             check_varname(method.site, name)
-        if isinstance(e, Expression):
+        if (isinstance(e, Expression)
+            and not (name == '_'
+                     and method.astcode.site.dml_version() != (1, 2))):
             inlined_arg = (
                 mkInlinedParam(method.site, e, name, e.ctype())
                 if defined(e) else e)
@@ -3881,7 +3910,9 @@ def codegen_method(site, inp, outp, throws, independent, memoization, ast,
     with (crep.DeviceInstanceContext() if not independent
           else contextlib.nullcontext()):
         for (arg, etype) in inp:
-            fnscope.add_variable(arg, type=etype, site=site, make_unique=False)
+            if not (arg == '_' and ast.site.dml_version() != (1, 2)):
+                fnscope.add_variable(arg, type=etype, site=site,
+                                     make_unique=False)
         initializers = [get_initializer(site, parmtype, None, None, None)
                         for (_, parmtype) in outp]