Support '_' as the 'discard 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.md

@@ -367,3 +367,23 @@
   _ = throwing_method();
   (_, x, _) = method_with_multiple_return_values();
   ```
+- '`_`' 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
+  _unused_. These contexts are:
+    - Method-local bindings (e.g. variables and input parameters.)
+
+      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.
+    - Index variables for object arrays
+
+      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.
+
+  Note that as a consequence of these semantics, any reference to '`_`' in code
+  will _always_ resolve to the discard reference.

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](dml-builtins.html#object) for more information.
 
 </dd><dt>
 
@@ -3175,6 +3184,28 @@ local (bool a, int i) = m();
 In the absence of explicit initializer expressions, a default
 "all zero" initializer will be applied to each declared object.
 
+"\_" may be used as an identifier for local variables, as well as other
+method-local bindings such as the method parameters, the bound identifier
+in `foreach`/`#foreach`/`#select` statements, and message component parameters
+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,
+may require multiple lines.
+
 ### Session Statements
 <pre>
 session <em>type</em> <em>identifier</em> [= <em>initializer</em>];
@@ -4064,6 +4095,7 @@ independent method callback(int i, void *aux) {
 ```
 
 ### The Discard Reference (`_`)
+<a id="discard-reference"/>
 ```
 _
 ```
@@ -4072,10 +4104,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.
@@ -4089,6 +4117,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

@@ -498,12 +498,25 @@ 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
 the object (any events associated with subobjects are unaffected).

py/dml/ast.py

@@ -48,14 +48,15 @@ def __setstate__(self, data):
     'case_dml12',
     'cast',
     'cdecl',
+    'cdecl_maybe_discarded',
     'compound',
     'conditional',
     'constant',
     'continue',
     'default',
     'default_dml12',
     'delete',
-    'discardref',
+    'discard',
     'dml',
     'dml_typedef',
     'dowhile',

py/dml/c_backend.py

@@ -249,8 +249,8 @@ def generate_structfile(device, filename, outprefix):
                     "%s(%s)" % (name,
                                 ", ".join((["conf_object_t *_obj"]
                                            * (not func.independent))
-                                          + [t.declaration(n)
-                                             for (n, t) in (
+                                          + [decl
+                                             for (_, _, decl) in (
                                                 func.cparams
                                                 if func.independent
                                                 else func.cparams[1:])]))))
@@ -718,7 +718,7 @@ def wrap_method(meth, wrapper_name, indices=()):
     is a port object
     """
 
-    inparams = [t.declaration(p) for p, t in meth.inp]
+    inparams = [p.declaration() for p in meth.inp]
     if not meth.outp:
         retvar = None
         rettype = TVoid()
@@ -749,7 +749,7 @@ def wrap_method(meth, wrapper_name, indices=()):
                                                  None, None, None)).toc()
 
         with LogFailure(meth.site, meth, indices):
-            inargs = [mkLit(meth.site, v, t) for v, t in meth.inp]
+            inargs = [mkLit(meth.site, p.c_ident, p.typ) for p in meth.inp]
             outargs = [mkLit(meth.site, v, t) for v, t in meth.outp]
             codegen_call(meth.site, meth,
                          indices,
@@ -804,10 +804,10 @@ def generate_implement_method(device, ifacestruct, meth, indices):
             # currently impossible to implement a varargs interface
             # method in DML
             raise EMETH(meth.site, None, 'interface method is variadic')
-        for ((mp, mt), it) in zip(meth.inp, iface_input_types):
-            if not safe_realtype_unconst(mt).eq(safe_realtype_unconst(it)):
+        for (mp, it) in zip(meth.inp, iface_input_types):
+            if not safe_realtype_unconst(mp.typ).eq(safe_realtype_unconst(it)):
                 raise EARGT(meth.site, 'implement', meth.name,
-                            mt, mp, it, 'method')
+                            mp.typ, mp.logref, it, 'method')
         if iface_num_outputs and dml.globals.dml_version != (1, 2):
             [(_, mt)] = meth.outp
             if not safe_realtype_unconst(mt).eq(
@@ -1355,15 +1355,15 @@ def generate_events(device):
 def generate_reg_callback(meth, name):
     dev_t = crep.structtype(dml.globals.device)
     out('static bool\n')
-    params = [t.declaration(p) for p, t in meth.inp] + [
+    params = [p.declaration() for p in meth.inp] + [
         TPtr(t).declaration(p) for p, t in meth.outp]
     out('%s(void *_obj, const uint16 *indices, ' % (name,)
         + ', '.join(params) + ')\n')
     out('{\n', postindent = 1)
     out('%s *_dev = _obj;\n' % dev_t)
     fail = ReturnFailure(meth.site)
     with fail, crep.DeviceInstanceContext():
-        inargs = [mkLit(meth.site, n, t) for n, t in meth.inp]
+        inargs = [mkLit(meth.site, p.c_ident, p.typ) for p in meth.inp]
         outargs = [mkLit(meth.site, "*" + n, t) for n, t in meth.outp]
         code = [codegen_call(
                 meth.site, meth,
@@ -2029,48 +2029,50 @@ def generate_init(device, initcode, outprefix):
 def generate_static_trampoline(func):
     # static trampolines never need to be generated for independent methods
     assert not func.independent
-    params = [("_obj", TPtr(TNamed("conf_object_t")))] + func.cparams[1:]
-    params_string = ('void' if not params
-                     else ", ".join(t.declaration(n) for (n, t) in params))
+
+    params_string = ''.join(", " + decl for (_, _, decl) in func.cparams[1:])
     start_function_definition(func.rettype.declaration(
-        "%s(%s)" % ("_trampoline" + func.get_cname(), params_string)))
+        "%s(conf_object_t *_obj%s)" % ("_trampoline" + func.get_cname(),
+                                       params_string)))
     out("{\n", postindent=1)
     out('ASSERT(_obj);\n')
     out('ASSERT(SIM_object_class(_obj) == _dev_class);\n')
-    (name, typ) = func.cparams[0]
-    out("%s = (%s)_obj;\n" % (typ.declaration(name), typ.declaration("")))
+    (name, typ, decl) = func.cparams[0]
+    out("%s = (%s)_obj;\n" % (decl, typ.declaration("")))
     out("%s%s(%s);\n" % ("" if func.rettype.void
                          else func.rettype.declaration("result") + " = ",
                          func.get_cname(),
-                         ", ".join(n for (n, t) in func.cparams)))
+                         ", ".join(n for (n, _, _) in func.cparams)))
     output_dml_state_change(name)
     if not func.rettype.void:
         out("return result;\n")
     out("}\n", preindent=-1)
 
 def generate_extern_trampoline(exported_name, func):
-    params = (func.cparams if func.independent else
-              [("_obj", TPtr(TNamed("conf_object_t")))] + func.cparams[1:])
-    params_string = ('void' if not params
-                     else ", ".join(t.declaration(n) for (n, t) in params))
+    cparams = list(func.cparams)
+    if not func.independent:
+        cparams[0] = (
+            '_obj', TPtr(TNamed("conf_object_t")),
+            TPtr(TNamed("conf_object_t")).declaration('_obj'))
+    params_string = ('void' if not cparams else ", ".join(
+                     decl for (_, _, decl) in cparams))
     out("extern %s\n" % (func.rettype.declaration(
                          "%s(%s)" % (exported_name, params_string))))
     out("{\n", postindent=1)
     out("%s%s(%s);\n" % ("return " * (not func.rettype.void),
                          "_trampoline" * (not func.independent)
                          + func.get_cname(),
-                         ", ".join(n for (n, t) in params)))
+                         ", ".join(n for (n, _, _) in cparams)))
     out("}\n", preindent=-1)
 
 def generate_extern_trampoline_dml12(exported_name, func):
     out("static UNUSED %s\n" % (func.rettype.declaration(
-        "%s(%s)" % (exported_name,
-                    ", ".join(t.declaration(n)
-                              for (n, t) in func.cparams)))))
+        "%s(%s)" % (exported_name,", ".join(
+            decl for (_, _, decl) in func.cparams)))))
     out("{\n", postindent=1)
     out("%s%s(%s);\n" % ("" if func.rettype.void else "return ",
                          func.get_cname(),
-                         ", ".join(n for (n, t) in func.cparams)))
+                         ", ".join(n for (n, _, _) in func.cparams)))
     out("}\n", preindent=-1)
 
 def generate_each_in_table(trait, instances):
@@ -2204,7 +2206,7 @@ def generate_adjustor_thunk(traitname, name, inp, outp, throws, independent,
     assert vtable_trait is def_path[-1]
     implicit_inargs = vtable_trait.implicit_args()
     preargs = crep.maybe_dev_arg(independent) + implicit_inargs
-    inargs = c_inargs(inp, outp, throws)
+    inargs = [(p.c_ident, p.typ) for p in inp] + c_extra_inargs(outp, throws)
     out('(%s)\n{\n' % (", ".join(t.declaration(n) for (n, t) in (preargs
                                                                  + inargs))),
         postindent=1)
@@ -2747,11 +2749,12 @@ def resolve_trait_param_values(node):
 
 def generate_trait_trampoline(method, vtable_trait):
     implicit_inargs = vtable_trait.implicit_args()
-    explicit_inargs = c_inargs(list(method.inp), method.outp, method.throws)
-    inparams = ", ".join(
-        t.declaration(n)
-        for (n, t) in (crep.maybe_dev_arg(method.independent) + implicit_inargs
-                       + explicit_inargs))
+    extra_inargs = c_extra_inargs(method.outp, method.throws)
+    inparams = ", ".join([t.declaration(n)
+                          for (n, t) in (crep.maybe_dev_arg(method.independent)
+                                         + implicit_inargs)]
+                         + [p.declaration() for p in method.inp]
+                         + [t.declaration(n) for (n, t) in extra_inargs])
     rettype = c_rettype(method.outp, method.throws)
 
     # guaranteed to exist; created by ObjTraits.mark_referenced
@@ -2772,7 +2775,8 @@ def generate_trait_trampoline(method, vtable_trait):
                 reduce(operator.mul, obj.dimsizes[dim + 1:], 1),
                 obj.dimsizes[dim]), TInt(32, False))
             for dim in range(obj.dimensions)]
-        args = [mkLit(site, n, t) for (n, t) in explicit_inargs]
+        args = ([mkLit(site, p.c_ident, p.typ) for p in method.inp]
+                + [mkLit(site, n, t) for (n, t) in extra_inargs])
         call_expr = mkcall_method(site, func, indices)(args)
     if not rettype.void:
         out('return ')
@@ -3376,9 +3380,10 @@ def generate_cfile_body(device, footers, full_module, filename_prefix):
         generated_funcs.add(func)
         code = codegen_method_func(func)
 
-        specializations = [(n, 'undefined' if undefined(v) else v.value)
-                           for (n, v) in func.inp
-                           if isinstance(v, Expression)]
+        specializations = [(p.ident,
+                            'undefined' if undefined(p.expr) else p.expr.value)
+                           for p in func.inp
+                           if p.ident is not None and p.expr is not None]
 
         if gather_size_statistics:
             ctx = StrOutput(lineno=output.current().lineno,