View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Dave Cross > Symbol-Approx-Sub > Symbol::Approx::Sub



Annotate this POD

Related Modules



Open  0
View/Report Bugs
Module Version: v3.0.2   Source  


Symbol::Approx::Sub - Perl module for calling subroutines by approximate names!


  use Symbol::Approx::Sub;

  sub a {
    # blah...

  aa(); # executes a() if aa() doesn't exist.

  use Symbol::Approx::Sub (xform => 'Text::Metaphone');
  use Symbol::Approx::Sub (xform => undef,
                           match => 'String::Approx');
  use Symbol::Approx::Sub (xform => 'Text::Soundex');
  use Symbol::Approx::Sub (xform => \&my_transform);
  use Symbol::Approx::Sub (xform => [\&my_transform, 'Text::Soundex']);
  use Symbol::Approx::Sub (xform => \&my_transform,
                           match => \&my_matcher,
                           choose => \&my_chooser);


This is _really_ stupid. This module allows you to call subroutines by _approximate_ names. Why you would ever want to do this is a complete mystery to me. It was written as an experiment to see how well I understood typeglobs and AUTOLOADing.

To use it, simply include the line:

  use Symbol::Approx::Sub;

somewhere in your program. Then, each time you call a subroutine that doesn't exist in the the current package, Perl will search for a subroutine with approximately the same name. The meaning of 'approximately the same' is configurable. The default is to find subroutines with the same Soundex value (as defined by Text::Soundex) as the missing subroutine. There are two other built-in matching styles using Text::Metaphone and String::Approx. To use either of these use:

  use Symbol::Approx::Sub (xform => 'Text::Metaphone');


  use Symbol::Approx::Sub (xform => undef,
                           match => 'String::Approx');

when using Symbol::Approx::Sub.

Configuring The Fuzzy Matching

There are three phases to the matching process. They are:

You can override any of these behaviours by writing your own transformer, matcher or chooser. You can either define the subroutine in your own script or you can put the subroutine in a separate module which Symbol::Approx::Sub can then use as a plug-in. See below for more details on plug-ins.

To use your own function, simply pass a reference to the subroutine to the use Symbol::Approx::Sub line like this:

  use Symbol::Approx::Sub(xform => \&my_transform,
                          match => \&my_matcher,
                          choose => \&my_chooser);

A plug-in is simply a module that lives in the Symbol::Approx::Sub namespace. For example, if you had a line of code like this:

  use Symbol::Approx::Sub(xform => 'MyTransform');

then Symbol::Approx::Sub will try to load a module called Symbol::Approx::Sub::MyTransform and it will use a function from within that module called transform as the transform function. Similarly, the matcher function is called match and the chooser function is called choose.

The default transformer, matcher and chooser are available as plug-ins called Text::Soundex, String::Equal and Random.

Subroutines ^


Called when the module is used. This function installs our AUTOLOAD subroutine into the caller's symbol table.


I can't stress too strongly that this will make your code completely unmaintainable and you really shouldn't use this module unless you're doing something very stupid.


This idea came to me whilst sitting in Mark-Jason Dominus' "Tricks of the Wizards" tutorial. In order to protect his reputation, I should probably point out that just as the idea was forming in my head, he clearly said that this kind of thing was a very bad idea.

Leon Brocard is clearly as mad as me as he pointed out some important bugs and helped massively with the 'fuzzy-configurability'.

Matt Freake helped by pointing out that Perl generally does what you mean, not what you think it should do.

Robin Houston spotted some nasty problems and (more importantly) supplied patches.


Dave Cross <>

With lots of help from Leon Brocard <>


Copyright (C) 2000-2008, Magnum Solutions Ltd. All Rights Reserved.

This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself.



syntax highlighting: