Are Options and named default arguments like oil and water in a Scala API?

Question

I'm working on a Scala API (for Twilio, by the way) where operations have a pretty large amount of parameters and many of these have sensible default values. To reduce typing and increase usability, I've decided to use case classes with named and default arguments. For instance for the TwiML Gather verb:

case class Gather(finishOnKey: Char = '#',                    numDigits: Int = Integer.MAX_VALUE, // Infinite                   callbackUrl: Option[String] = None,                    timeout: Int = 5                   ) extends Verb 

The parameter of interest here is callbackUrl. It is the only parameter which is really optional in the sense that if no value is supplied, no value will be applied (which is perfectly legal).

I've declared it as an option in order to do the monadic map routine with it on the implementation side of the API, but this puts some extra burden on the API user:

Gather(numDigits = 4, callbackUrl = Some("http://xxx")) // Should have been Gather(numDigits = 4, callbackUrl = "http://xxx")  // Without the optional url, both cases are similar Gather(numDigits = 4) 

As far as I can make out, there are two options (no pun intended) to resolve this. Either make the API client import an implicit conversion into scope:

implicit def string2Option(s: String) : Option[String] = Some(s) 

Or I can redeclare the case class with a null default and convert it to an option on the implementation side:

case class Gather(finishOnKey: Char = '#',                    numDigits: Int = Integer.MAX_VALUE,                    callbackUrl: String = null,                    timeout: Int = 5                   ) extends Verb 

My questions are as follows:

1. Are there any more elegant ways to solve my particular case?
2. More generally: Named arguments is a new language feature (2.8). Could it turn out that Options and named default arguments are like oil and water? :)
3. Might using a null default value be the best choice in this case?

Answer 1

Here's another solution, partly inspired by Chris' answer. It also involves a wrapper, but the wrapper is transparent, you only have to define it once, and the user of the API doesn't need to import any conversions:

class Opt[T] private (val option: Option[T]) object Opt {    implicit def any2opt[T](t: T): Opt[T] = new Opt(Option(t)) // NOT Some(t)    implicit def option2opt[T](o: Option[T]): Opt[T] = new Opt(o)    implicit def opt2option[T](o: Opt[T]): Option[T] = o.option }  case class Gather(finishOnKey: Char = '#',                    numDigits: Opt[Int] = None, // Infinite                   callbackUrl: Opt[String] = None,                    timeout: Int = 5                  ) extends Verb  // this works with no import Gather(numDigits = 4, callbackUrl = "http://xxx") // this works too Gather(numDigits = 4, callbackUrl = Some("http://xxx")) // you can even safely pass the return value of an unsafe Java method Gather(callbackUrl = maybeNullString()) 

---

To address the larger design issue, I don't think that the interaction between Options and named default parameters is as much oil-and-water as it might seem at first glance. There's a definite distinction between an optional field and one with a default value. An optional field (i.e. one of type Option[T]) might never have a value. A field with a default value, on the other hand, simply does not require its value to be supplied as an argument to the constructor. These two notions are thus orthogonal, and it's no surprise that a field may be optional and have a default value.

That said, I think a reasonable argument can be made for using Opt rather than Option for such fields, beyond just saving the client some typing. Doing so makes the API more flexible, in the sense that you can replace a T argument with an Opt[T] argument (or vice-versa) without breaking callers of the constructor[1].

As for using a null default value for a public field, I think this is a bad idea. "You" may know that you expect a null, but clients that access the field may not. Even if the field is private, using a null is asking for trouble down the road when other developers have to maintain your code. All the usual arguments about null values come into play here -- I don't think this use case is any special exception.

[1] Provided that you remove the option2opt conversion so that callers must pass a T whenever an Opt[T] is required.

Answer 2

Don't auto-convert anything to an Option. Using my answer here, I think you can do this nicely but in a typesafe way.

sealed trait NumDigits { /* behaviour interface */ } sealed trait FallbackUrl { /* behaviour interface */ } case object NoNumDigits extends NumDigits { /* behaviour impl */ } case object NofallbackUrl extends FallbackUrl { /* behaviour impl */ }  implicit def int2numd(i : Int) = new NumDigits { /* behaviour impl */ } implicit def str2fallback(s : String) = new FallbackUrl { /* behaviour impl */ }  class Gather(finishOnKey: Char = '#',                numDigits: NumDigits = NoNumDigits, // Infinite               fallbackUrl: FallbackUrl = NoFallbackUrl,                timeout: Int = 5 

Then you can call it as you wanted to - obviously adding your behaviour methods to FallbackUrl and NumDigits as appropriate. The main negative here is that it is a ton of boilerplate

Gather(numDigits = 4, fallbackUrl = "http://wibble.org")