记录Scala 2.10宏 [英] Documenting Scala 2.10 macros

问题描述

我将从一个例子开始。这个等价于Scala 2.10中作为宏的元组的 List.fill ：

  import scala.language.experimental.macros 
 import scala.reflect.macros.Context 
 
对象TupleExample {
 def fill [A]（arity：Int）（a ：A）：Product = macro fill_impl [A] 
 
 def fill_impl [A]（c：Context）（arity：c.Expr [Int]）（a：c.Expr [A]）= {
 import c.universe._ 
 
 arity.tree match {
 case Literal（Constant（n：Int））如果n < 23 => c.Expr（
 Apply（
 Select（Ident（Tuple+ n.toString），apply），
 List.fill（n）（a.tree）
）
）
 case _ => c.abort（
 c.enclosingPosition，
希望的天赋必须是小于23的编译时常数！
）
} 
} 
 } 
  

我们可以使用以下方法：

 阶> TupleExample.fill（3）（hello）
 res0：（String，String，String）=（hello，hello，hello）
  

这个家伙在几个方面是一只奇怪的鸟。首先， arity 参数必须是一个字面整数，因为我们需要在编译时使用它。在以前的Scala版本中，没有办法（据我所知）一种方法，甚至可以判断其中一个参数是否是编译时文字。

第二，产品返回类型是一个谎言 - 静态返回类型将包含由参数确定的特定理由和元素类型，如上所示。

那么我将如何记录这个东西？在这一点上，我并不期待Scaladoc的支持，但是我希望有一种约定或最佳实践的感觉（除了确保编译时错误消息是清楚的），这将使得运行到一个宏方法中对于Scala 2.10图书馆的用户来说，潜在的奇怪的需求并不令人惊讶。

新宏观系统最成熟的演示（例如， ScalaMock ， Slick ，其他列在此处的其他人仍然相对无证件在方法级别。任何一个例子或指针都将被赞赏，包括来自具有类似宏系统的其他语言的例子。

解决方案

我认为最好的文档这些是使用示例代码，正如迈尔斯在他的实验基于宏的分支无形。

I'll start with an example. Here's an equivalent of List.fill for tuples as a macro in Scala 2.10:

import scala.language.experimental.macros
import scala.reflect.macros.Context

object TupleExample {
  def fill[A](arity: Int)(a: A): Product = macro fill_impl[A]

  def fill_impl[A](c: Context)(arity: c.Expr[Int])(a: c.Expr[A]) = {
    import c.universe._

    arity.tree match {
      case Literal(Constant(n: Int)) if n < 23 => c.Expr(
        Apply(
          Select(Ident("Tuple" + n.toString), "apply"),
          List.fill(n)(a.tree)
        )
      )
      case _ => c.abort(
        c.enclosingPosition,
        "Desired arity must be a compile-time constant less than 23!"
      )
    }
  }
}

We can use this method as follows:

scala> TupleExample.fill(3)("hello")
res0: (String, String, String) = (hello,hello,hello)

This guy is a weird bird in a couple of respects. First, the arity argument must be a literal integer, since we need to use it at compile time. In previous versions of Scala there was no way (as far as I know) for a method even to tell whether one of its arguments was a compile-time literal or not.

Second, the Product return type is a lie—the static return type will include the specific arity and element type determined by the arguments, as shown above.

So how would I document this thing? I'm not expecting Scaladoc support at this point, but I'd like to have a sense of conventions or best practices (beyond just making sure the compile-time error messages are clear) that would make running into a macro method—with its potentially bizarre demands—less surprising for users of a Scala 2.10 library.

The most mature demonstrations of the new macro system (e.g., ScalaMock, Slick, the others listed here) are still relatively undocumented at the method level. Any examples or pointers would be appreciated, including ones from other languages with similar macro systems.

解决方案

I think the best way to document these is with example code, as Miles has been doing in his experimental macro based branch of shapeless.

这篇关于记录Scala 2.10宏的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！