lower a' as var"'"(a) (#34634)

Author: simeonschaub

NEWS.md

@@ -70,6 +70,11 @@ Language changes
 * The line number of function definitions is now added by the parser as an
   additional `LineNumberNode` at the start of each function body ([#35138]).
 
+* Statements of the form `a'` now get lowered to `var"'"(a)` instead of `Base.adjoint(a)`. This
+  allows for shadowing this function in local scopes, although this is generally discouraged.
+  By default, Base exports `var"'"` as an alias of `Base.adjoint`, so custom types should still
+  extend `Base.adjoint`. ([#34634])
+
 Compiler/Runtime improvements
 -----------------------------
 

base/docs/basedocs.jl

@@ -486,26 +486,6 @@ Expr
 """
 Expr
 
-"""
-    '
-
-The conjugate transposition operator, see [`adjoint`](@ref).
-
-# Examples
-```jldoctest
-julia> A = [1.0 -2.0im; 4.0im 2.0]
-2×2 Array{Complex{Float64},2}:
- 1.0+0.0im  -0.0-2.0im
- 0.0+4.0im   2.0+0.0im
-
-julia> A'
-2×2 Array{Complex{Float64},2}:
-  1.0-0.0im  0.0-4.0im
- -0.0+2.0im  2.0-0.0im
-```
-"""
-kw"'"
-
 """
     \$
 

base/exports.jl

@@ -459,6 +459,7 @@ export
     startswith,
 
 # linear algebra
+    var"'", # to enable syntax a' for adjoint
     adjoint,
     transpose,
     kron,

base/operators.jl

@@ -542,6 +542,8 @@ for op in (:+, :*, :&, :|, :xor, :min, :max, :kron)
     end
 end
 
+const var"'" = adjoint
+
 """
     \\(x, y)
 

src/julia-syntax.scm

@@ -2338,7 +2338,7 @@
                      ,.(apply append rows)))
             `(call (top typed_vcat) ,t ,@a)))))
 
-   '|'|  (lambda (e) (expand-forms `(call (top adjoint) ,(cadr e))))
+   '|'|  (lambda (e) (expand-forms `(call |'| ,(cadr e))))
 
    'generator
    (lambda (e)

stdlib/LinearAlgebra/src/adjtrans.jl

@@ -100,10 +100,14 @@ Base.unaliascopy(A::Union{Adjoint,Transpose}) = typeof(A)(Base.unaliascopy(A.par
 
 # wrapping lowercase quasi-constructors
 """
+    A'
     adjoint(A)
 
-Lazy adjoint (conjugate transposition) (also postfix `'`).
-Note that `adjoint` is applied recursively to elements.
+Lazy adjoint (conjugate transposition). Note that `adjoint` is applied recursively to
+elements.
+
+For number types, `adjoint` returns the complex conjugate, and therefore it is equivalent to
+the identity function for real numbers.
 
 This operation is intended for linear algebra usage - for general data manipulation see
 [`permutedims`](@ref Base.permutedims).
@@ -119,6 +123,14 @@ julia> adjoint(A)
 2×2 Adjoint{Complex{Int64},Array{Complex{Int64},2}}:
  3-2im  8-7im
  9-2im  4-6im
+
+julia> x = [3, 4im]
+2-element Array{Complex{Int64},1}:
+ 3 + 0im
+ 0 + 4im
+
+julia> x'x
+25 + 0im
 ```
 """
 adjoint(A::AbstractVecOrMat) = Adjoint(A)

stdlib/REPL/src/docview.jl

@@ -43,7 +43,8 @@ function _helpmode(io::IO, line::AbstractString)
     x = Meta.parse(line, raise = false, depwarn = false)
     assym = Symbol(line)
     expr =
-        if haskey(keywords, assym) || Base.isoperator(assym) || isexpr(x, :error) || isexpr(x, :invalid)
+        if haskey(keywords, Symbol(line)) || Base.isoperator(assym) || isexpr(x, :error) ||
+            isexpr(x, :invalid) || isexpr(x, :incomplete)
             # Docs for keywords must be treated separately since trying to parse a single
             # keyword such as `function` would throw a parse error due to the missing `end`.
             assym

test/syntax.jl

@@ -2269,3 +2269,10 @@ _temp_33553 = begin
 end
 @test _temp_33553 == 2
 @test !@isdefined(_x_this_remains_undefined)
+
+# lowering of adjoint
+@test (1 + im)' == 1 - im
+x = let var"'"(x) = 2x
+    3'
+end
+@test x == 6