new syntax for lvalue references: var b {.byaddr.} = expr

[timotheecour]

TLDR

• introduces a new syntax for lvalue references: var b {.byaddr.} = expr, eg:

var b {.byaddr.} = foo[0].funWithSideEffect(2).bar.myStr
# simply use b, it'll be via reference semantically
b.add "foo"

• exact analog of C++ references auto& b = expr;
• much better approach than existing alternatives:

## existing alternative 1: template
template a: untyped = expr
  # * will evaluate expr each time it's used (even if costly, or has side effects)
  # * won't detect invalid `expr` if `a` is unused
  # * doesn't give redefinition errors

## existing alternative 2: let
let a = expr # not a reference, does a copy

## existing alternative 3: explicit `addr`
let a = expr.addr
a[]+=2 # less convenient: requires a deref on each use
fun(a) # less safe: the reference can escape

• supersedes [superseded] new syntax for lvalue references: byaddr x = expr #13342 which can be closed if this is merged
• supersedes [superseded] ref syntax for lvalue expressions: byRef: myref=x[1].foo[2] #11824 which can be closed if this is merged
• see [superseded] ref syntax for lvalue expressions: byRef: myref=x[1].foo[2] #11824 for rationale, examples etc

compared to #13342 and #11824

(some of these are comparisons to only #13342 or only #11824 or both)

• no parser change
• gives clean redefinition error despite [compiler bug] template redefinition silently accepted; should give Error: redefinition error #8275
  in particular giving a redefinition error with [superseded] ref syntax for lvalue expressions: byRef: myref=x[1].foo[2] #11824 approach would've been trickier to do correctly (we should only check in current scope)

# using #11824 approach:
import sugar
var x = @[1,2,3]
byAddr: x1=x[1]
x1+=10
byAddr: x1=x[2] # should give a redifinition error but doesn't, and hard to do (`when declared` is too naive)

• allows specifying type optionally:
  var b {.byaddr.}: int = s[0]
• doesn't introduce a new keyword, only a new pragma just for var for now; so it's easier to extend, eg var b {.byunsafeaddr.}: int = s[0] if needed
• syntax is just a pragma extension of a regular let statement
• addresses the essential technical criticism from [superseded] new syntax for lvalue references: byaddr x = expr #13342 (comment)

And personally I would have used let/var x {.view.} = someLocation. Adding a new pragma before a new keyword seems good and so does keeping the let vs var distinction.

I can change to view which is short and explicit, but I'd rather do the change just once, after this is greenlighted

example

    var s = @[10,11,12]
    var a {.byaddr.} = s[0]
    a+=100
    doAssert s == @[110,11,12]
    doAssert a is int
    var b {.byaddr.}: int = s[0]
    doAssert a.addr == b.addr

future PR's

• for now the var section with byaddr must have a single element, support for more than 1 could be added in future (will be backward compatible of course)

# ok
var
  b {.byaddr.} = expr

# not implemented
var
  b1 = expr1
  b2 {.byaddr.} = expr2
  b3 {.byaddr.} = expr2

• we could introduce let b {.byaddr.} = expr if needed
• tuple ref-unpacking as proposed here Nested tuple unpacking RFCs#194 (comment):

var x = (1, 2)
var (a,b) {.byaddr.} = x

note

this should replace at least some use cases for shallowCopy and {.shallow.}

[Araq]

Pretty good. However, either use an AST to AST transformation inside semexprs only without the helper public symbols in system.nim, or let's fix pragmas for variables so that is can be done entirely as a template/macro.

[kaushalmodi]

@timotheecour Can you please also document this in the manual in the Pragmas section: https://nim-lang.github.io/Nim/manual#pragmas ? Thanks.

[krux02]

Aren't references a feature that is left out in Nim for reasons?

[timotheecour]

@Araq PTAL

or let's fix pragmas for variables so that is can be done entirely as a template/macro.

done

compiler now lowers var a {.foo.}: MyType = expr to foo(a, MyType, expr) with user defined foo (with appropriate checks)

there are othe applications for this new compiler feature besides the current byaddr, eg:

# wraps a decl behind getter and setter accessors, eg for debugging
var {.onAccessCallback.} x: int 

[timotheecour]

@Araq friendly ping (I'll rebase to fix changelog.md conflict after you greenlight this as the changelog changes often)