"since versions" for symbols
============================

Token syntax
------------

Most compact, but harder to implement:
    1.2
Easy to implement:
    "1.2"
    @1.2



Syntax alternative 1
--------------------
    type T since 1.2 = struct {
    }
    func f() since 1.2 -> void

pros:
cons:
- a detail that is easy to miss during code review
- needs separate syntax for type/data/functions

Syntax alternative 2
--------------------
    since @1.2
    
    type T = struct {
    }
    func f() -> void

pros:
+ less repetition
+ easy to read
+ easy to implement
cons:
- related function can get spread out
- easy to miss newer (and possibly better) APIs
- easy to miss that "since" keyword if there are many symbols in a version
- confusing if the since and the symbol are on adjacent lines

Syntax alternative 3
--------------------
    since 1.2
    type T = struct {
    }

    since 1.2
    func f() -> void

pros:
+ easy to read
+ easy to implement
cons:
- one extra line for each symbol
- confusing if the since and the symbol are NOT on adjacent lines (but that can be forbidden)

Syntax alternative 3
--------------------
    since 1.2 type T = struct {
    }

    since 1.2 func f() -> void

pros:
+ easy to implement
cons:
- long lines
- makes it harder to visually find a certain symbol

Syntax alternative 4
--------------------
    type T@1.2 = struct {
    }

    func f@1.2() -> void

pros:
+ compact
+ easiest to implement?
+ could allow overriding of symbols also!
cons:
- might be confusing for new users?
should @xxx be required even for the initial version? might be a good idea, to indicate that the ABI is stable

this syntax could be extended, to allow for deprecation or deletion of symbols:

    deprecate T@1.2.1
    delete T@1.3

(if the system ABI allows it, it would be possible to extend this to *changes*
of symbols also, but that would limit portability)

references to versioned symbols.
for example:

    type T@1.1 = struct { ... }
    type U@1.2 = struct {
        ref T@1.1 t
    }

for now, it could just be implemented as normal identifiers, with some extra
information about the version in the IdentDecl


syntax alternative 5
--------------------
    type @1.2 T = struct {
    }

    func @1.2 f() -> void

pros:
- easy to implement (along with alt. 2)
- readable (version is not "inside" definition)
cons:
- makes searching harder

this can also be extended with deprecate/delete:

    deprecate @1.2.1 type T
    delete @1.3 type T


Syntax alternative 6
--------------------
    versionsection @1.2

    type T = struct {
    }
    func f() -> void

 --or (@@@ is used by diffs)--
    @@1.2

    type T = struct {
    }
    func f() -> void

pros:
+ less repetition
+ easy to read
+ easy to implement
cons:
- related function can get spread out
- easy to miss newer (and possibly better) APIs
- easy to miss that "since" keyword if there are many symbols in a version