Finish draft on QME

dmiller · dmiller · commit 408e6c7b313c · 2024-09-05T19:26:28.000-04:00
diff --git a/_drafts/2024-08-05-qualified-methods-for-ClojureCLR.md b/_drafts/2024-08-05-qualified-methods-for-ClojureCLR.md
@@ -1,19 +1,19 @@
 ---
 layout: post
-title: Qualfied methods -- for ClojureCLR
-date: 2024-08-05 00:00:00 -0500
+title: Qualified methods -- for ClojureCLR
+date: 2024-09-05 00:00:00 -0500
 categories: general
 ---
 
-Clojure has introduced a new _qualified methods_ feature allows for Java methods to be passed to higher-order functions.  This feature also provides alternative ways to invoke methods and constructors, and new ways to specify type hints.  We need to enhance this mechanism for ClojureCLR in the same way we enhanced 'classic' interop. 
+Clojure has introduced a new _qualified methods_ feature allows for Java methods to be passed to higher-order functions.  This feature also provides alternative ways to invoke methods and constructors, and new ways to specify type hints.  We need to enhance this mechanism for ClojureCLR in the same ways we enhanced 'classic' interop. 
 
 I'll start with a quick review of 'classic' interop, including the additions made for interop with the CLR.
-I'll introduce the new qualified methods mechanism.  
+I'll (quickly) survey the new qualified methods mechanism.  
 I'll conclude with looking at how the CLR extras will be incorporated in the new mechanism.
 
 # 'Classic' interop
 
-I'm going to assume basic familiarity with interoperabiltiy with the JVM/CLR, at least prior to the introduction of qualified methods.  If you need a refresher, you can look at the [Java interop section](https://clojure.org/reference/java_interop) of the Clojure reference.  
+I'm going to assume basic familiarity with interoperabiltiy with the JVM/CLR (prior to the introduction of qualified methods).  If you need a refresher, you can look at the [Java interop section](https://clojure.org/reference/java_interop) of the Clojure reference.  
 
 There are several pages on the ClojureCLR wiki that talk about the additional features of CLR interop:
 
@@ -35,7 +35,24 @@ Symbols that represent the names of types are resolved to `Type` objects.
 
 Classes can be `import`ed into a Clojure namespece so that the namespace of the type can be omitted, as with `String` above. (There is a default set of imports that are always available.  See the note at the end for how that set is computed.)
 
-There are types in the CLR that can not be named by symbols.  (I guess Java does not yet have this problem.) See the note at the end for a few comments about this.
+## Interlude: Specifying type names
+There are types in the CLR that can not be named by symbols, or at least symbols that the Lisp reader can parse.  (I guess Java does not yet have this problem.) See the note at the end for a few comments about this. The 
+[specifying types](https://github.com/clojure/clojure-clr/wiki/Specifying-types) page explains how we get around this.   It is just ugly.  The mechanism ties directly into the CLR's type naming and resolution machinery, thus:
+
+```clojure
+|System.Collections.Generic.IList`1[System.Int32]|
+```
+
+You have to include fully-qualified type names, generics include a backtick and the number of type arguments, and the type arguments are enclosed in square brackets. 
+
+> I plan to introduce a new syntax for this in ClojureCLR.Next that would take advantage of imports and be otherwise nice.
+When I designed the `|...|` syntax (stolen from CommonLisp), Clojure did not yet have _tagged literals_.  Now we might be able to do something like
+> 
+```
+#type "IList<int>"
+```
+>
+> (If you are interested in helping to design this, please let me know.)
 
 ## Member access
 
@@ -58,59 +75,53 @@ For CLR interop, we had to add some additional functionality, primarily for call
 If you are familiar with C#, you have seen `ref`, `in`, and `out` used in method signatures.  There is no distinction of these at the CLR level.  C# adds `in` and `out` for additional compile-time analysis.  Given that we don't have uninitialized variables in Clojure and that CLR doesn't distinguish, ClojureCLR only provide a `by-ref` mechanism.  The example given on the wiki page looks at a class defined by:
 
 ```C#
-public class C1
+public class AlmostEverything
 {
-    public int m3(int x) { return x; }
-    public int m3(ref int x) { x = x + 1; return x+20; }
-    public string m5(string x, ref int y) { y = y + 10;  return x + y.ToString(); }
-    public int m5(int x, ref int y) { y = y + 100; return x+y; }
+    public int Out(int x) { return x + 10; }
+    public int Out(ref int x) { x += 1; return x + 20; }
+
+    public string Ambig(string x, ref int y) { y += 10; return x + y.ToString(); }
+     public int Ambig(int x, ref int y) { y 
 }
 ```
 
-To call `m3` with a `ref` argument, you would use:
+To call `Out` with a `ref` argument, you would use:
 
 ```clojure
-(let [n (int n)  ]
-  (.m3 c (by-ref n)))
+(let [m (int n)  ]
+  (.out c (by-ref m)))
 ```
 
 The type hint provided by the `(int n)` is required -- otherwise the it will try to match a `ref object` parameter.
 
-The `by-ref` is a syntactic form that can only be used at the top-level of interop calls, as shown here. It can only wrap a local variable. (`by-ref` can also be used in `definterface`, `deftype`, and the like.)  And yes, the value of the local variable `n` is updated by the call -- yep, that binding is not immutable.  You do not want to know how this is done.
+The `by-ref` is a syntactic form that can only be used at the top-level of interop calls, as shown here. It can only wrap a local variable. (`by-ref` can also be used in `definterface`, `deftype`, and the like.)  And yes, the value of the local variable `n` is updated by the call -- that binding is not immutable.  You do not want to know how this is done.
 
 For `params`, consider the class:
 
 ```C#
-namespace dm.interop
+public class ParamsTest
 {
-  public class C6
-  {
-    public static int sm1(int x, params object[] ys)
+    public static int StaticParams(int x, params object[] ys)
     {
         return x + ys.Length;
     }
-   public static int sm1(int x, params string[] ys)
+   public static int StaticParams(int x, params string[] ys)
     {
         int count = x;
         foreach (String y in ys)
             count += y.Length;
         return count;
     }
-   public static int m2(ref int x, params object[] ys)
-   {
-        x += ys.Length;
-        return ys.Length;
-    }
-  }
+  
 }
 ```
 
-Method `sm1` is overloaded on the `params` argument.
+Method `StaticParams` is overloaded on the `params` argument.
 You can access the first overload with either of these:
 
 ```clojure
-(dm.interop.C6/sm1 12 #^objects (into-array Object [1 2 3] ))
-(dm.interop.C6/sm1 12 #^"System.Object[]" (into-array Object  [1 2 3]))
+(ParamsTest/StaticParams 12 #^objects (into-array Object [1 2 3] ))
+(ParamsTest/StaticParams 12 #^"System.Object[]" (into-array Object  [1 2 3]))
 ```
 
 The second overload is accessed with:
@@ -119,19 +130,9 @@ The second overload is accessed with:
 (dm.interop.C6/sm1 12 #^"System.String[]" (into-array String ["abc" "de" "f"]))
 (dm.interop.C6/sm1 12 #^"System.String[]" (into-array ["abc" "de" "f"]))
 ```
-
-Make me one with everything.
-
-```clojure
-(defn c6m2 [x] 
-  (let [n (int x)
-        v (dm.interop.C6/m2 (by-ref n) #^objects (into-array Object [1 2 3 4]))]
-    [n v]))
-```
-
 ## Generic methods
 
-We are talking here about methods with type paremeters, not methods that are part of a generic type.
+We are talking here about methods with type parameters, not methods that are part of a generic type.
 Often you don't need to do anything special:
 
 ```clojure
@@ -194,8 +195,7 @@ By invocation we mean appearing as the first element in a `(func args)` form.  T
 ```
 
 For static methods, this is our original syntax.  For instance methods, this would compare to `(.ToUpper ^String s)`.
-The third example is equivalent to `(String. \a 12)`.   We gain the ability to directly specify the type on the instance method.
-(Though see `:param-tags` below for a bonus.)
+The third example is equivalent to `(String. \a 12)`.   We gain the ability to directly specify the type via the namespace of the symbol.
 
 Using qualified methods as values is the more interesting case.  Rather than needing to wrap a method in a function, as in
 
@@ -214,8 +214,7 @@ Note that we no longer need the type hint on the parameter to avoid reflection.
 
 Using qualified methods gives us the benefit of a type hint on the instance variable for instance method invocation. In fact, the type that the qualified method gives (`String` in the case of `String/.ToUpper`) overrides any type hint on the instance argument.
 
-For invocations, further disambiguation of method signature can be made by providing type hints on the other arguments.   
-However, for use in value positions, we cannot type hint in this way.
+For invocations, further disambiguation of method signature can be made by providing type hints on the other arguments.  
 
 Consider trying to map `Math/Abs` over a sequence.  In the old `IFn`-wrapper style
 
@@ -235,7 +234,7 @@ Now consider using a qualified method:
  (map Math/Abs [1.23 -3.14])
 ```
 
-You will get a reflection warning.  And there is no place to put a traditional type hint.
+You still will get a reflection warning.  And there is no place to put a traditional type hint.
 
 Enter `:param-tags`.  You can add `:param-tags` metadata to the qualified method to provide type hints.  The easiest way to  The easiest way is to use new `^[...]` metadata reader syntax.
 
@@ -271,13 +270,13 @@ For one argument, not a big deal.  But with, say, 3 arguments, it might help to
 
 At least you have a choice.
 
-## the add-ons
+## The CLR add-ons
 
-We need to allow adding `(type-args ...)` and `(by-ref ...)` to our `:param-tags`.
+We need to allow adding `(type-args ...)`  to our `:param-tags`.
 Simply, we just put them into position.
 
 ```clojure
-#[(type-args T1 T2) T3 T4 (by-ref T5)] T/.m
+#[(type-args T1 T2) T3 T4 |T5&|] T/.m
 ```
 
 would specify the instance method 
@@ -289,8 +288,9 @@ class T
 }
 ```
 
-I don't know if there is any utility for `by-ref` in things like `map` calls.  You would have no way to get any changed value in a `by-ref` parameter.
-A fallback to the classic interop using a function wrapper seems best for this situation.
+Note also the use of the reference type `T5&` for the by-ref parameter.
+
+I don't know if there is any utility for `by-ref` in things like `map` calls.  You would have no way to get any changed value in a `by-ref` parameter.  A fallback to the classic interop using a function wrapper seems best for this situation.
 
 
 ## Availability 
@@ -309,24 +309,4 @@ The new qualified methods feature is available in ClojureCLR 1.12-alpha10 and la
 - the type is not a generic type definition  (meaning an uintantiated generic type)
 - the type's name does not start with "_" or "<".
 
-In addition, strictly for my own convenience for dealing with 'core.clj' and other startup files, I add `System.Text.StringBuilder`, `clojure.lang.BigInteger` and `clojure.lang.BigDecimal`.  (I'll change `clojure.lang.BigInteger` to `System.Numerics.BigInteger` in the ClojureCLR.Next.)
-
-
-## Note: Specifying type names
-
- The 
-[specifying types](https://github.com/clojure/clojure-clr/wiki/Specifying-types) page explains how we get around this.   It is just ugly.  The mechanism ties directly into the CLR's type naming and resolution machinery, thus:
-
-```clojure
-|System.Collections.Generic.IList`1[System.Int32]|
-```
-
-You have to include fully-qualified type names, generics include a backtick and the number of type arguments, and the type arguments are enclosed in square brackets. 
-
-I plan to introduce a new syntax for this in ClojureCLR.Next, that would take advantage of imports and be otherwise nice.
-When I designed the `|...|` syntax (stolen from CommonLisp), Clojure did not yet have _tagged literals_.  Now we might be able to do something like
-
-#type "IList<int>"
-
-(If you are interested in helping to design this, please let me know.)
-
+In addition, strictly for my own convenience for dealing with 'core.clj' and other startup files, I add `System.Text.StringBuilder`, `clojure.lang.BigInteger` and `clojure.lang.BigDecimal`.  (I'll change `clojure.lang.BigInteger` to `System.Numerics.BigInteger` in  ClojureCLR.Next.)
