How to create an extensible API, and still use object initializer syntax?

Question

I have a class library that wraps the command line client for Mercurial.

My intention is to implement support for all the built-in commands, but in addition to those, there's a ton of extensions out there.

So I need to make my library extendable in the sense that both others and I can add support for extensions. I plan on adding support for some of the more popular and typical extensions (at the very least quite a few of those that come bundled with Mercurial), but I still want to be able to extend it from the outside.

At the moment, the syntax of a command look like this:

Repo.Execute(new CommitCommand
{
    Message = "Your commit message",
    AddRemove = true,
});

This, however, doesn't lend itself very easily to extensions, without the programmer feeling that the extension is just a tacked on part.

For instance, let's assume I expose a public collection of additional command line arguments, to that I could manually do this:

var cmd = new CommitCommand
{
    Message = "Your commit message",
    AddRemove = true,
};
cmd.Arguments.Add("--my-commit-extension");
Repo.Execute(cmd);

There seems to be no easy way for me to get that additional extension added in such a way that it can be set as part of the object initializer.

I've been thinking of adding, or perhaps switching, to a fluent interface syntax. In this case, you could write something like this:

Repo.Execute(new CommitCommand()
    .Message("Your commit message")
    .AddRemove()
    .MyCommitExtension());

However, I see people don't like fluent interfaces, they feel they become too chatty.

What other options do I have?

What I want, basically:

• One common syntax style
  • For both built-in things
  • As well as extensions added by users of my library

I envision that users of my library would extend it by adding new classes, and extension methods to get intellisense support, but extension methods can't be used in object initializers, which means that all extensions look like some afterthought. That's not what I want.

Any ideas are welcome.

Answer 1

I'm not familier with Mercurial and your question seems too general to address specifically, but I can address one particular comment.

var cmd = new CommitCommand 
{ 
    Message = "Your commit message", 
    AddRemove = true, 
}; 
cmd.Arguments.Add("--my-commit-extension"); 
Repo.Execute(cmd); 

If CommitCommand.Arguments is IList<T> you already have the ability to use initializer syntax:

class CommitCommand
{
    public string Message { get; set; }
    public bool AddRemove { get; set; }
    public List<string> Arguments = new List<string>();
}

Repo.Execute(new CommitCommand
{
    Message = "Your commit message",
    AddRemove = true,
    Arguments = { "--my-commit-extension", "--my-other-commit-extension" }
});

Answer 2

I too am not that familiar with Mercurial, but one option is to throw intellisense out and use anonymous types:

Repo.Execute(new 
{
    Message = "Your commit message",
    AddRemove = true,
    MyCommitExtension = null
});

You cannot use hyphens in property names, so you'd need to substitute from PascalCase to hyphen-lower-case. Alternatively you could just replace underscores with hypens.

I'm not sure I'd recommend this approach without knowing more about the frequency with which people are going to use these extensions. This approach works well in the ASP.NET MVC framework when dealing with HTML attributes, but that scenario is different in that the framework doesn't need to handle the values, it just writes them into the output directly. If you are taking conditional actions based upon the values provided in this way, or you want your API to be more discoverable to those who don't know Mercurial's command line syntax, then you might try another approach.

Answer 3

As for me fluent interface is ok. But if you want to avoid it, then I would probably use smth like this:

interface IExtension { ... }

class SomeExtension1 : IExtension { ... }
class SomeExtension2 : IExtension { ... }

class CommitCommand
{
    public string Message;
    public bool AddRemove;
    public readonly IList<IExtension> Extensions = new List<IExtension>();
}

It will allow to use commands in this way:

new CommitCommand
{
    Message = "",
    AddRemove = true,
    Extensions = {new SomeExtension1(), new SomeExtension2()}
};