Author image Jon Schutz
and 1 contributors


Sphinx::Config - Sphinx search engine configuration file read/modify/write


    use Sphinx::Config;

    my $c = Sphinx::Config->new();
    $path = $c->get('index', 'test1', 'path');
    $c->set('index', 'test1', 'path', $path);



    $c = Sphinx::Config->new;


    $pi = $c->preserve_inheritance(1);

Set/get the current behaviour for preserving inherited values. When set to a non-zero value (the default), if a value is set in a parent section, then it is automatically inherited by any child sections, and when the configuration file is saved, values that are implicit through inheritance are not shown. When set to zero, each section is considered standalone and a complete set of values is shown in the saved file.

This flag may be enabled and disabled selectively for calls to set() and save().




Parse the given Sphinx configuration file.

Dies on errors.


    $c->parse_string( $string );

Parse the Sphinx configuration in the given string.

Dies on errors.


    $config = $c->config;

Get the parsed configuration data as an array of hashes, where each entry in the array represents one section of the configuration, in the order as parsed or constructed.

Each section is described by a hash with the following keys:

  • _type A mandatory key describing the section type (index, searchd etc)

  • _name The name of the section, where applicable

  • _inherited The name of the parent section, where applicable

  • _data A hash containing the name/value pairs which hold the configuration data for the section. All values are simple data elements, except where the same key can appear multiple times in the configuration file with different values (such as in attribute declarations), in which case the value is an array ref.

  • _inherited A hash describing which data values have been inherited


    $value = $c->get($type, $name, $varname)
    $value = $c->get($type, $name)

Get the value of a configuration parameter.

If $varname is specified, the value of the named parameter from the section identified by the type and name is returned as a scalar. Otherwise, the hash containing all key/value pairs from the section is returned.

$name may be undef for sections that do not require a name (e.g. searchd, indexer, search).

If the section cannot be found or the named parameter does not exist, undef is returned.


    $c->set($type, $name, $varname, $value)
    $c->set($type, $name, \%values)
    $c->set($type, $name, undef(), $base_name)
    $c->set($type, $name, \%values, $base_name)

Set the value or values of a section in the configuration.

If varname is given, then the single parameter of that name in the given section is set to the specified value. If the value is an array, multiple entries will be created in the output file for the same key.

If a hash of name/value pairs is given, then any existing values are replaced with the given hash.

    $c->set('source', , $name, \%values);

If the section does not currently exist, a new one is appended.

Set $name to undef to set variables in an indexer, searchd or search section.

    $c->set('indexer', undef, 'listen', $port);
    $c->set('search', undef, \%values );

To change the section's inheritance, set $value to undef and specify a value in the 4th parameter.

    $c->set('source', 'src1', undef(), 'base2');

You this may be combined with a hash variable :

    $c->set('source', 'src1', \%values, 'base_source');

To delete a name/value pair, set $value to undef.

    $c->set('source', 'src1', 'sql_query_pre', undef());
    $c->set('source', 'src1', 'sql_query_pre');

Returns the hash containing the current data values for the given section.

See preserve_inheritance for a description of how inherited values are handled.


    $c->save($filename, $comment)

Save the configuration to a file. The currently opened file is used if not specified.

The comment is inserted literally, so each line should begin with '#'.

See preserve_inheritance for a description of how inherited blocks are handled.


    $s = $c->as_string
    $s = $c->as_string($comment)

Returns the configuration as a string, optionally with a comment prepended.

The comment is inserted literally, so each line should begin with '#'.

An effort has been made to make the configuration round-trip safe. That is, any formating or comments in the original should also appear as-is in the generated configuration. New sections are added at the end of the configuration with an 8 space indent.

New variables added to existing sections are handled as follows:

  • If you add a new variable to an existing section, it is added at the end of the section, using the whitespace of the last existing variable.


        index foo {
            biff= bof
            # ...

    and you add honk with the value bonk, you will end up with:

        index foo {
            biff= bof
            # ...
            honk= bonk
  • If you have a comment that looks a bit like the default or commented out variable, the new value is added after the comment.


        index foo {
            # honk=foo
            # more details

    and you add honk with the value bonk, you will end up with:

        index foo {
            # honk=foo
            honk = bonk
            # more details


    $s = $c->as_string_new
    $s = $c->as_string_new($comment)

Returns the configuration as a string, optionally with a comment prepended, without attempting to preserve formatting from the original file.

The comment is inserted literally, so each line should begin with '#'.




Jon Schutz, <jon at>


Please report any bugs or feature requests to bug-sphinx-config at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc Sphinx::Config

You can also look for information at:


Philip Gwyn contributed the patch to preserve round-trip formatting, which was a significant chunk of work.


Copyright 2007 Jon Schutz, all rights reserved.

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