Using configuration records and operators to reduce number of overloaded methods

When writing libraries you sometimes want to provide users (that is, programmers) with a flexible API. If a specific part of your library can be used in different ways, you may want to provide multiple overloaded methods accepting different combinations of parameters.

For example, IOmniPipeline interface from OmniThreadLibrary implements three overloaded Stage functions.

function  Stage(pipelineStage: TPipelineSimpleStageDelegate; 
  taskConfig: IOmniTaskConfig = nil): IOmniPipeline; overload;

function  Stage(pipelineStage: TPipelineStageDelegate; 
  taskConfig: IOmniTaskConfig = nil): IOmniPipeline; overload;

function  Stage(pipelineStage: TPipelineStageDelegateEx; 
  taskConfig: IOmniTaskConfig = nil): IOmniPipeline; overload;

Delphi’s own System.Threading is even worse. In class TParallel, for example, there are 32 overloads of the &For class function. Thirty two! Not only it is hard to select appropriate function; it is also hard to decode something useful from the code completion tip. Check the image below – can you tell which overloaded version I’m trying to call? Me neither!

Because of all that, it is usually good to minimize number of overloaded methods. We can do some work by adding default parameters, but sometimes this doesn’t help. Today I’d like to present an alternative solution – configuration records and operator overloading. To simplify things, I’ll present a mostly made-up problem. You can download it from github.

An example

type
  TConnector = class
  public
    procedure SetupBridge(const url1, url2: string); overload;
    procedure SetupBridge(const url1, proto2, host2, path2: string); overload;
    procedure SetupBridge(const proto1, host1, path1, proto2, host2, path2: string); overload;
//    procedure SetupBridge(const proto1, host1, path1, url2: string); overload;
  end;

This class expects two URL parameters but allows the user to provide them in different forms – either as a full URL (for example, ‘http://www.thedelphigeek.com/index.html’) or as (protocol, host, path) triplets (for example, ‘http’, ‘www.thedelphigeek.com’, ‘index.html’). Besides the obvious problem of writing – and maintaining – four overloads this code exhibits another problem. We simply cannot provide all four alternatives to the user!

The problem lies in the fact that the second and fourth (commented out) overload both contain four string parameters. Delphi doesn’t allow that – and for a good reason! If we could define both at the same time, the compiler would have absolutely no idea which method to call if we write SetupBridge(‘1’, ‘2’, ‘3’, ‘4’). Both versions would be equally valid candidates!

So – strike one. We cannot even write the API that we would like to provide. Even worse – the user may get confused and may expect that we did provide the fourth version and they try to use it. Like this:

conn := TConnector.Create;
try
  conn.SetupBridge('http://www.thedelphigeek.com/index.html',
                   'http://bad.horse/');
  conn.SetupBridge('http://www.thedelphigeek.com/index.html',
                   'http', 'bad.horse', '');
  conn.SetupBridge('http', 'www.thedelphigeek.com', 'index.html',
                   'http', 'bad.horse', '');
  // this compiles, ouch:
  conn.SetupBridge('http', 'www.thedelphigeek.com', 'index.html',
                   'http://bad.horse/');
 finally
   FreeAndNil(conn);
 end;

Although the last call to SetupBridge compiles, it does something that user doesn’t expect. The code calls the second SetupBridge overload and sets url 1 to ‘http’ and url 2 to (‘www.thedelphigeek.com’, ‘index.html’, ‘http://bad.horse/’). Strike two. The output of the program proves that (all ‘1:’ lines should be equal, as should be all ‘2:’ lines):

Last but not least – the API is not very good. When we need to pass lots of configuration to a method, it is better to pack the configuration into meaningful units. So – strike three and out. Let’s rewrite the code!

A solution

Records are good solution for packing configuration into meaningful units. Let’s try and rewrite the API to use record-based configuration.

TURL = record
end;

TConnector2 = class
public
  procedure SetupBridge(const url1, url2: TURL);
end;

Much better. Just one overload! Still, there’s a problem of putting information inside the TURL record.

I could add a bunch of properties and write:

url1.Proto := 'http';
url1.Host := 'www.thedelphigeek.com';
url1.Path := 'index.html';
url2.URL := 'http://bad.horse/';
conn2.SetupBridge(url1, url2);

Clumsy. I have to declare two variables and type lots of code. No.

I could also create two constructors and write:

conn2.SetupBridge(TURL.Create('http', 'www.thedelphigeek.com', 'index.html'),
                  TURL.Create('http://bad.horse/'));
conn2.SetupBridge(TURL.Create('http://www.thedelphigeek.com/index.html'),
                  TURL.Create('http://bad.horse/'));

That looks better, but still – in the second SetupBridge call both TURL.Create calls look completely out of place. Do I have to pull back and rewrite my API like this?

TConnector = class
public
  procedure SetupBridge(const url1, url2: string); overload;
  procedure SetupBridge(const url1: string; const url2: TURL); overload;
  procedure SetupBridge(const url1, url2: TURL); overload;
  procedure SetupBridge(const url1: TURL; const url2: string); overload;
end;

Well, yes, this is a possibility. It solves the problem of supporting all four combinations and it nicely puts related information into one unit. Still, we can do better. Operators to the rescue!

I’m quite happy with the Create approach for providing an information triplet. it is the other variant – the one with just a single URL parameter – that I would like to simplify. I would just like to provide a simple string when the URL is in one piece.

To support that, we only have to add an Implicit operator which converts a string into a TURL record. (Another one converting TURL into a string is also helpful as it simplifies the use of TURL inside the TConnector class.)

Here is full implementation for TURL:

  TURL = record
  strict private
    FUrl: string;
  public
    constructor Create(const proto, host, path: string);
    class operator Implicit(const url: string): TURL;
    class operator Implicit(const url: TURL): string;
  end;

constructor TURL.Create(const proto, host, path: string);
begin
  FURL := proto + '://' + host + '/' + path;
end;

class operator TURL.Implicit(const url: string): TURL;
begin
  Result.FURL := url;
end;

class operator TURL.Implicit(const url: TURL): string;
begin
  Result := url.FURL;
end;

Simple, isn’t it? The implementation uses the fact that TConnector has no need to access separate URL components. It is quite happy with the concatenated version, created in the TURL.Create.

This allows us to provide parameters in a way that is – at least for me – a good compromise. It allows for a (relatively) simple use and the implementation is also (relatively) simple:

conn2 := TConnector2.Create;
try
  conn2.SetupBridge('http://www.thedelphigeek.com/index.html',
                    'http://bad.horse/');
  conn2.SetupBridge('http://www.thedelphigeek.com/index.html',
                    TURL.Create('http', 'bad.horse', ''));
  conn2.SetupBridge(TURL.Create('http', 'www.thedelphigeek.com', 'index.html'),
                    TURL.Create('http', 'bad.horse', ''));
  // this works as expected:
  conn2.SetupBridge(TURL.Create('http', 'www.thedelphigeek.com', 'index.html'),
                    'http://bad.horse/');
finally
  FreeAndNil(conn2);
end;

The output from the program shows that everything is OK now: