Using configuration records and operators to reduce number of overloaded methods

[Primož Gabrijelčič 223]

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 &Forclass 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:

[Rollo62 536]

Dear Primoz,

 

thanks for the nice article.

For me personally (this is not that I want to convince everybody), I like and use another pattern quite often in such cases:

 

conn.SetupBridge_FromRelative(url : String);
conn.SetupBridge_FromAbsolute(url : String);
conn.SetupBridge_FromXxxx(    ....);

This makes it a lot easier for me to choose the right version, and I got clear parameter lists,
on the cost of longer function names, of coarse.
Since I'm a friend of long and "speaking" names, this is not a big problem to me, but I can confess this can get nasty in some situations too.

Rollo

 

 

[Uwe Raabe 2057]

You can even shorten the TURL.Create by introducing a function URL wrapping around that. This is similar to TRect.Create and Rect. As a drawback it somewhat litters your scope.

[Stefan Glienke 2002]

The benefit of the TUrl type opposed to differently named overloads is also that you declare a domain type and make the API cleaner than just (string, string, string) regardless the naming of the parameters

[Kryvich 165]

In the right pascal way it would be like this:

type
  TUrl = type string;
  TProto = type string;
  THost = type string;
  TPath = type string;

TConnector = class
  public
    procedure SetupBridge(const url1, url2: TUrl); overload;
    procedure SetupBridge(const url1: TUrl;
      const proto2: TProto; const host2: THost; path2: TPath); overload;
    procedure SetupBridge(const proto1: TProto; const host1: THost; path1: TPath;
      proto2: TProto; const host2: THost; path2: TPath); overload;
    procedure SetupBridge(const proto1: TProto; const host1: THost; path1: TPath;
      url2: TUrl); overload;
  end;

The type in "TUrl = type string" means that TUrl is a new different string type. Then you would need to specify the type of the parameter when calling:

    Connector.SetupBridge(TUrl('http://www.thedelphigeek.com/index.html'),
      TUrl('http://bad.horse/'));
    Connector.SetupBridge(TUrl('http://www.thedelphigeek.com/index.html'),
      TProto('http'), THost('bad.horse'), TPath(''));

So are we safe? No! Unfortunately, Delphi allows assignments between custom string types.

Connector.SetupBridge('http://www.thedelphigeek.com/index.html', 'http://bad.horse/');
Connector.SetupBridge(TProto('http://www.thedelphigeek.com/index.html'), TProto('http://bad.horse/'));

There is no overloaded methods like "procedure SetupBridge(const url1, url2: TProto);". But the compiler will not give any warning or hint.

I would like the compiler developers to add a hint in such situations, not only for the types generated from string, but also for any other types (Integer, Byte etc.)

[Stefan Glienke 2002]

6 minutes ago, Kryvich said:

In the right pascal way it would be like this:

And after that you show why the "right" way is bad...

An URL consists of different parts which combined give a string, yes but should be represented as the different parts, hence the record.

Especially since there are cases where such a type cannot just be represented as string or number but consists of different data of different types. Yes there might be a string representation but it should not be passed as that through your API.

[Kryvich 165]

@Stefan Glienke I do not argue with the solution proposed by Gabrijelčič. But I would like to be warned when parameters of a wrong type are passed to API functions. A small hint from the compiler would help avoid difficult-to-find errors.

[Stefan Glienke 2002]

1 minute ago, Kryvich said:

A small hint from the compiler would help avoid difficult-to-find errors.

Agreed, type redeclaration is really not very helpful in many situations.

- you still have implicit type compatibility no matter what

- but helpers stop working