{ "content": [ { "type": "text", "text": "# Config::General (perldoc)\n\n## NAME\n\nConfig::General - Generic Config Module\n\n## SYNOPSIS\n\n#\n# the OOP way\nuse Config::General;\n$conf = Config::General->new(\"rcfile\");\nmy %config = $conf->getall;\n#\n# the procedural way\nuse Config::General qw(ParseConfig SaveConfig SaveConfigString);\nmy %config = ParseConfig(\"rcfile\");\n\n## DESCRIPTION\n\nThis module opens a config file and parses its contents for you. The new method requires one\nparameter which needs to be a filename. The method getall returns a hash which contains all\noptions and its associated values of your config file.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **SUBROUTINES/METHODS** (44 subsections)\n- **CONFIG FILE FORMAT**\n- **BLOCKS**\n- **NAMED BLOCKS**\n- **WHITESPACE IN BLOCKS**\n- **EXPLICIT EMPTY BLOCKS** (1 subsections)\n- **LONG LINES**\n- **HERE DOCUMENTS**\n- **INCLUDES** (1 subsections)\n- **COMMENTS**\n- **PARSER PLUGINS**\n- **OBJECT ORIENTED INTERFACE**\n- **VARIABLE INTERPOLATION**\n- **EXPORTED FUNCTIONS**\n- **CONFIGURATION AND ENVIRONMENT**\n- **SEE ALSO**\n- **LICENSE AND COPYRIGHT**\n- **BUGS AND LIMITATIONS**\n- **INCOMPATIBILITIES**\n- **DIAGNOSTICS**\n- **DEPENDENCIES**\n- **AUTHOR**\n- **VERSION**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Config::General", "section": "", "mode": "perldoc", "summary": "Config::General - Generic Config Module", "synopsis": "#\n# the OOP way\nuse Config::General;\n$conf = Config::General->new(\"rcfile\");\nmy %config = $conf->getall;\n#\n# the procedural way\nuse Config::General qw(ParseConfig SaveConfig SaveConfigString);\nmy %config = ParseConfig(\"rcfile\");", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 11, "subsections": [] }, { "name": "DESCRIPTION", "lines": 11, "subsections": [] }, { "name": "SUBROUTINES/METHODS", "lines": 1, "subsections": [ { "name": "new", "lines": 23 }, { "name": "-ConfigFile", "lines": 4 }, { "name": "-ConfigHash", "lines": 4 }, { "name": "-String", "lines": 9 }, { "name": "-AllowMultiOptions", "lines": 7 }, { "name": "-LowerCaseNames", "lines": 4 }, { "name": "-UseApacheInclude", "lines": 6 }, { "name": "-IncludeRelative", "lines": 9 }, { "name": "-IncludeDirectories", "lines": 5 }, { "name": "-IncludeGlob", "lines": 7 }, { "name": "-IncludeAgain", "lines": 9 }, { "name": "-ConfigPath", "lines": 11 }, { "name": "-MergeDuplicateBlocks", "lines": 5 }, { "name": "-MergeDuplicateOptions", "lines": 7 }, { "name": "-AutoLaunder", "lines": 6 }, { "name": "-AutoTrue", "lines": 13 }, { "name": "-FlagBits", "lines": 70 }, { "name": "-DefaultConfig", "lines": 7 }, { "name": "-Tie", "lines": 27 }, { "name": "-InterPolateVars", "lines": 3 }, { "name": "-InterPolateEnv", "lines": 4 }, { "name": "-AllowSingleQuoteInterpolation", "lines": 3 }, { "name": "-ExtendedAccess", "lines": 3 }, { "name": "-StrictObjects", "lines": 6 }, { "name": "-StrictVars", "lines": 4 }, { "name": "-SplitPolicy", "lines": 20 }, { "name": "-SplitDelimiter", "lines": 3 }, { "name": "-StoreDelimiter", "lines": 8 }, { "name": "-CComments", "lines": 6 }, { "name": "-BackslashEscape", "lines": 2 }, { "name": "-SlashIsDirectory", "lines": 36 }, { "name": "-UseApacheIfDefine", "lines": 2 }, { "name": "-Define", "lines": 23 }, { "name": "-ApacheCompatible", "lines": 24 }, { "name": "-UTF8", "lines": 3 }, { "name": "-SaveSorted", "lines": 3 }, { "name": "-NoEscape", "lines": 3 }, { "name": "-NormalizeBlock", "lines": 11 }, { "name": "-NormalizeOption", "lines": 2 }, { "name": "-NormalizeValue", "lines": 2 }, { "name": "getall", "lines": 2 }, { "name": "files", "lines": 2 }, { "name": "save_file", "lines": 32 }, { "name": "save_string", "lines": 14 } ] }, { "name": "CONFIG FILE FORMAT", "lines": 14, "subsections": [] }, { "name": "BLOCKS", "lines": 89, "subsections": [] }, { "name": "NAMED BLOCKS", "lines": 27, "subsections": [] }, { "name": "WHITESPACE IN BLOCKS", "lines": 32, "subsections": [] }, { "name": "EXPLICIT EMPTY BLOCKS", "lines": 58, "subsections": [ { "name": "array", "lines": 34 } ] }, { "name": "LONG LINES", "lines": 13, "subsections": [] }, { "name": "HERE DOCUMENTS", "lines": 38, "subsections": [] }, { "name": "INCLUDES", "lines": 20, "subsections": [ { "name": "new", "lines": 49 } ] }, { "name": "COMMENTS", "lines": 31, "subsections": [] }, { "name": "PARSER PLUGINS", "lines": 98, "subsections": [] }, { "name": "OBJECT ORIENTED INTERFACE", "lines": 3, "subsections": [] }, { "name": "VARIABLE INTERPOLATION", "lines": 3, "subsections": [] }, { "name": "EXPORTED FUNCTIONS", "lines": 36, "subsections": [] }, { "name": "CONFIGURATION AND ENVIRONMENT", "lines": 2, "subsections": [] }, { "name": "SEE ALSO", "lines": 10, "subsections": [] }, { "name": "LICENSE AND COPYRIGHT", "lines": 5, "subsections": [] }, { "name": "BUGS AND LIMITATIONS", "lines": 2, "subsections": [] }, { "name": "INCOMPATIBILITIES", "lines": 2, "subsections": [] }, { "name": "DIAGNOSTICS", "lines": 2, "subsections": [] }, { "name": "DEPENDENCIES", "lines": 3, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "Config::General - Generic Config Module\n", "subsections": [] }, "SYNOPSIS": { "content": "#\n# the OOP way\nuse Config::General;\n$conf = Config::General->new(\"rcfile\");\nmy %config = $conf->getall;\n\n#\n# the procedural way\nuse Config::General qw(ParseConfig SaveConfig SaveConfigString);\nmy %config = ParseConfig(\"rcfile\");\n", "subsections": [] }, "DESCRIPTION": { "content": "This module opens a config file and parses its contents for you. The new method requires one\nparameter which needs to be a filename. The method getall returns a hash which contains all\noptions and its associated values of your config file.\n\nThe format of config files supported by Config::General is inspired by the well known Apache\nconfig format, in fact, this module is 100% compatible to Apache configs, but you can also just\nuse simple name/value pairs in your config files.\n\nIn addition to the capabilities of an Apache config file it supports some enhancements such as\nhere-documents, C-style comments or multiline options.\n", "subsections": [] }, "SUBROUTINES/METHODS": { "content": "", "subsections": [ { "name": "new", "content": "Possible ways to call new():\n\n$conf = Config::General->new(\"rcfile\");\n\n$conf = Config::General->new(\\%somehash);\n\n$conf = Config::General->new( %options ); # see below for description of possible options\n\nThis method returns a Config::General object (a hash blessed into \"Config::General\"\nnamespace. All further methods must be used from that returned object. see below.\n\nYou can use the new style with hash parameters or the old style which is of course still\nsupported. Possible parameters to new() are:\n\n* a filename of a configfile, which will be opened and parsed by the parser\n\nor\n\n* a hash reference, which will be used as the config.\n\nAn alternative way to call new() is supplying an option- hash with one or more of the\nfollowing keys set:\n" }, { "name": "-ConfigFile", "content": "A filename or a filehandle, i.e.:\n\n-ConfigFile => \"rcfile\" or -ConfigFile => \\$FileHandle\n" }, { "name": "-ConfigHash", "content": "A hash reference, which will be used as the config, i.e.:\n\n-ConfigHash => \\%somehash\n" }, { "name": "-String", "content": "A string which contains a whole config, or an arrayref containing the whole config line\nby line. The parser will parse the contents of the string instead of a file. i.e:\n\n-String => $completeconfig\n\nit is also possible to feed an array reference to -String:\n\n-String => \\@configlines\n" }, { "name": "-AllowMultiOptions", "content": "If the value is \"no\", then multiple identical options are disallowed. The default is\n\"yes\". i.e.:\n\n-AllowMultiOptions => \"yes\"\n\nsee IDENTICAL OPTIONS for details.\n" }, { "name": "-LowerCaseNames", "content": "If set to a true value, then all options found in the config will be converted to\nlowercase. This allows you to provide case-in-sensitive configs. The values of the\noptions will not lowercased.\n" }, { "name": "-UseApacheInclude", "content": "If set to a true value, the parser will consider \"include ...\" as valid include\nstatement (just like the well known Apache include statement).\n\nIt also supports apache's \"IncludeOptional\" statement with the same behavior, that is,\nif the include file doesn't exist no error will be thrown.\n" }, { "name": "-IncludeRelative", "content": "If set to a true value, included files with a relative path (i.e. \"cfg/blah.conf\") will\nbe opened from within the location of the configfile instead from within the location of\nthe script($0). This works only if the configfile has a absolute pathname (i.e.\n\"/etc/main.conf\").\n\nIf the variable -ConfigPath has been set and if the file to be included could not be\nfound in the location relative to the current config file, the module will search within\n-ConfigPath for the file. See the description of -ConfigPath for more details.\n" }, { "name": "-IncludeDirectories", "content": "If set to a true value, you may specify include a directory, in which case all files\ninside the directory will be loaded in ASCII order. Directory includes will not recurse\ninto subdirectories. This is comparable to including a directory in Apache-style config\nfiles.\n" }, { "name": "-IncludeGlob", "content": "If set to a true value, you may specify a glob pattern for an include to include all\nmatching files (e.g. <>). Also note that as with standard file\npatterns, * will not match dot-files, so <> is often more desirable than\nincluding a directory with -IncludeDirectories.\n\nAn include option will not cause a parser error if the glob didn't return anything.\n" }, { "name": "-IncludeAgain", "content": "If set to a true value, you will be able to include a sub-configfile multiple times.\nWith the default, false, you will get a warning about duplicate includes and only the\nfirst include will succeed.\n\nReincluding a configfile can be useful if it contains data that you want to be present\nin multiple places in the data tree. See the example under \"INCLUDES\".\n\nNote, however, that there is currently no check for include recursion.\n" }, { "name": "-ConfigPath", "content": "As mentioned above, you can use this variable to specify a search path for relative\nconfig files which have to be included. Config::General will search within this path for\nthe file if it cannot find the file at the location relative to the current config file.\n\nTo provide multiple search paths you can specify an array reference for the path. For\nexample:\n\n@path = qw(/usr/lib/perl /nfs/apps/lib /home/lib);\n..\n-ConfigPath => \\@path\n" }, { "name": "-MergeDuplicateBlocks", "content": "If set to a true value, then duplicate blocks, that means blocks and named blocks, will\nbe merged into a single one (see below for more details on this). The default behavior\nof Config::General is to create an array if some junk in a config appears more than\nonce.\n" }, { "name": "-MergeDuplicateOptions", "content": "If set to a true value, then duplicate options will be merged. That means, if the same\noption occurs more than once, the last one will be used in the resulting config hash.\n\nSetting this option implies -AllowMultiOptions == false unless you set\n-AllowMultiOptions explicit to 'true'. In this case duplicate blocks are allowed and put\ninto an array but duplicate options will be merged.\n" }, { "name": "-AutoLaunder", "content": "If set to a true value, then all values in your config file will be laundered to allow\nthem to be used under a -T taint flag. This could be regarded as circumventing the\npurpose of the -T flag, however, if the bad guys can mess with your config file, you\nhave problems that -T will not be able to stop. AutoLaunder will only handle a config\nfile being read from -ConfigFile.\n" }, { "name": "-AutoTrue", "content": "If set to a true value, then options in your config file, whose values are set to true\nor false values, will be normalised to 1 or 0 respectively.\n\nThe following values will be considered as true:\n\nyes, on, 1, true\n\nThe following values will be considered as false:\n\nno, off, 0, false\n\nThis effect is case-insensitive, i.e. both \"Yes\" or \"No\" will result in 1.\n" }, { "name": "-FlagBits", "content": "This option takes one required parameter, which must be a hash reference.\n\nThe supplied hash reference needs to define variables for which you want to preset\nvalues. Each variable you have defined in this hash-ref and which occurs in your config\nfile, will cause this variable being set to the preset values to which the value in the\nconfig file refers to.\n\nMultiple flags can be used, separated by the pipe character |.\n\nWell, an example will clarify things:\n\nmy $conf = Config::General->new(\n-ConfigFile => \"rcfile\",\n-FlagBits => {\nMode => {\nCLEAR => 1,\nSTRONG => 1,\nUNSECURE => \"32bit\" }\n}\n);\n\nIn this example we are defining a variable named *\"Mode\"* which may contain one or more\nof \"CLEAR\", \"STRONG\" and \"UNSECURE\" as value.\n\nThe appropriate config entry may look like this:\n\n# rcfile\nMode = CLEAR | UNSECURE\n\nThe parser will create a hash which will be the value of the key \"Mode\". This hash will\ncontain all flags which you have pre-defined, but only those which were set in the\nconfig will contain the pre-defined value, the other ones will be undefined.\n\nThe resulting config structure would look like this after parsing:\n\n%config = (\nMode => {\nCLEAR => 1,\nUNSECURE => \"32bit\",\nSTRONG => undef,\n}\n);\n\nThis method allows the user (or, the \"maintainer\" of the configfile for your\napplication) to set multiple pre-defined values for one option.\n\nPlease beware, that all occurrences of those variables will be handled this way, there\nis no way to distinguish between variables in different scopes. That means, if \"Mode\"\nwould also occur inside a named block, it would also parsed this way.\n\nValues which are not defined in the hash-ref supplied to the parameter -FlagBits and\nused in the corresponding variable in the config will be ignored.\n\nExample:\n\n# rcfile\nMode = BLAH | CLEAR\n\nwould result in this hash structure:\n\n%config = (\nMode => {\nCLEAR => 1,\nUNSECURE => undef,\nSTRONG => undef,\n}\n);\n\n\"BLAH\" will be ignored silently.\n" }, { "name": "-DefaultConfig", "content": "This can be a hash reference or a simple scalar (string) of a config. This causes the\nmodule to preset the resulting config hash with the given values, which allows you to\nset default values for particular config options directly.\n\nNote that you probably want to use this with -MergeDuplicateOptions, otherwise a default\nvalue already in the configuration file will produce an array of two values.\n" }, { "name": "-Tie", "content": "-Tie takes the name of a Tie class as argument that each new hash should be based off\nof.\n\nThis hash will be used as the 'backing hash' instead of a standard Perl hash, which\nallows you to affect the way, variable storing will be done. You could, for example\nsupply a tied hash, say Tie::DxHash, which preserves ordering of the keys in the config\n(which a standard Perl hash won't do). Or, you could supply a hash tied to a DBM file to\nsave the parsed variables to disk.\n\nThere are many more things to do in tie-land, see tie to get some interesting ideas.\n\nIf you want to use the -Tie feature together with -DefaultConfig make sure that the hash\nsupplied to -DefaultConfig must be tied to the same Tie class.\n\nMake sure that the hash which receives the generated hash structure (e.g. which you are\nusing in the assignment: %hash = $config->getall()) must be tied to the same Tie class.\n\nExample:\n\nuse Config::General qw(ParseConfig);\nuse Tie::IxHash;\ntie my %hash, \"Tie::IxHash\";\n%hash = ParseConfig(\n-ConfigFile => shift(),\n-Tie => \"Tie::IxHash\"\n);\n" }, { "name": "-InterPolateVars", "content": "If set to a true value, variable interpolation will be done on your config input. See\nConfig::General::Interpolated for more information.\n" }, { "name": "-InterPolateEnv", "content": "If set to a true value, environment variables can be used in configs.\n\nThis implies -InterPolateVars.\n" }, { "name": "-AllowSingleQuoteInterpolation", "content": "By default variables inside single quotes will not be interpolated. If you turn on this\noption, they will be interpolated as well.\n" }, { "name": "-ExtendedAccess", "content": "If set to a true value, you can use object oriented (extended) methods to access the\nparsed config. See Config::General::Extended for more information.\n" }, { "name": "-StrictObjects", "content": "By default this is turned on, which causes Config::General to croak with an error if you\ntry to access a non-existent key using the OOP-way (-ExtendedAcess enabled). If you turn\n-StrictObjects off (by setting to 0 or \"no\") it will just return an empty\nobject/hash/scalar. This is valid for OOP-access 8via AUTOLOAD and for the methods\nobj(), hash() and value().\n" }, { "name": "-StrictVars", "content": "By default this is turned on, which causes Config::General to croak with an error if an\nundefined variable with InterPolateVars turned on occurs in a config. Set to *false*\n(i.e. 0) to avoid such error messages.\n" }, { "name": "-SplitPolicy", "content": "You can influence the way how Config::General decides which part of a line in a config\nfile is the key and which one is the value. By default it tries its best to guess. That\nmeans you can mix equalsign assignments and whitespace assignments.\n\nHowever, sometime you may wish to make it more strictly for some reason. In this case\nyou can set -SplitPolicy. The possible values are: 'guess' which is the default,\n'whitespace' which causes the module to split by whitespace, 'equalsign' which causes it\nto split strictly by equal sign, or 'custom'. In the latter case you must also set\n-SplitDelimiter to some regular expression of your choice. For example:\n\n-SplitDelimiter => '\\s*:\\s*'\n\nwill cause the module to split by colon while whitespace which surrounds the delimiter\nwill be removed.\n\nPlease note that the delimiter used when saving a config (savefile() or savestring())\nwill be chosen according to the current -SplitPolicy. If -SplitPolicy is set to 'guess'\nor 'whitespace', 3 spaces will be used to delimit saved options. If 'custom' is set,\nthen you need to set -StoreDelimiter.\n" }, { "name": "-SplitDelimiter", "content": "Set this to any arbitrary regular expression which will be used for option/value\nsplitting. -SplitPolicy must be set to 'custom' to make this work.\n" }, { "name": "-StoreDelimiter", "content": "You can use this parameter to specify a custom delimiter to use when saving configs to a\nfile or string. You only need to set it if you want to store the config back to disk and\nif you have -SplitPolicy set to 'custom'.\n\nHowever, this parameter takes precedence over whatever is set for -SplitPolicy.\n\nBe very careful with this parameter.\n" }, { "name": "-CComments", "content": "Config::General is able to notice c-style comments (see section COMMENTS). But for some\nreason you might no need this. In this case you can turn this feature off by setting\n-CComments to a false value('no', 0, 'off').\n\nBy default -CComments is turned on.\n" }, { "name": "-BackslashEscape", "content": "Deprecated Option.\n" }, { "name": "-SlashIsDirectory", "content": "If you turn on this parameter, a single slash as the last character of a named block\nwill be considered as a directory name.\n\nBy default this flag is turned off, which makes the module somewhat incompatible to\nApache configs, since such a setup will be normally considered as an explicit empty\nblock, just as XML defines it.\n\nFor example, if you have the following config:\n\n\nIndex index.awk\n\n\nyou will get such an error message from the parser:\n\nEndBlock \"\" has no StartBlock statement (level: 1, chunk 10)!\n\nThis is caused by the fact that the config chunk below will be internally converted to:\n\n\nIndex index.awk\n\n\nNow there is one '' too much. The proper solution is to use quotation to\ncircumvent this error:\n\n\nIndex index.awk\n\n\nHowever, a raw apache config comes without such quotes. In this case you may consider to\nturn on -SlashIsDirectory.\n\nPlease note that this is a new option (incorporated in version 2.30), it may lead to\nvarious unexpected side effects or other failures. You've been warned.\n" }, { "name": "-UseApacheIfDefine", "content": "Enables support for Apache ... . See -Define.\n" }, { "name": "-Define", "content": "Defines the symbols to be used for conditional configuration files. Allowed arguments:\nscalar, scalar ref, array ref or hash ref.\n\nExamples:\n\n-Define => 'TEST'\n-Define => \\$testOrProduction\n-Define => [qw(TEST VERBOSE)]\n-Define => {TEST => 1, VERBOSE => 1}\n\nSample configuration:\n\n\n\nLevel Debug\ninclude test/*.cfg\n\n\nLevel Notice\ninclude production/*.cfg\n\n\n" }, { "name": "-ApacheCompatible", "content": "Over the past years a lot of options has been incorporated into Config::General to be\nable to parse real Apache configs.\n\nThe new -ApacheCompatible option now makes it possible to tweak all options in a way\nthat Apache configs can be parsed.\n\nThis is called \"apache compatibility mode\" - if you will ever have problems with parsing\nApache configs without this option being set, you'll get no help by me. Thanks :)\n\nThe following options will be set:\n\nUseApacheInclude = 1\nIncludeRelative = 1\nIncludeDirectories = 1\nIncludeGlob = 1\nSlashIsDirectory = 1\nSplitPolicy = 'whitespace'\nCComments = 0\nUseApacheIfDefine = 1\n\nTake a look into the particular documentation sections what those options are doing.\n\nBeside setting some options it also turns off support for explicit empty blocks.\n" }, { "name": "-UTF8", "content": "If turned on, all files will be opened in utf8 mode. This may not work properly with\nolder versions of Perl.\n" }, { "name": "-SaveSorted", "content": "If you want to save configs in a sorted manner, turn this parameter on. It is not\nenabled by default.\n" }, { "name": "-NoEscape", "content": "If you want to use the data ( scalar or final leaf ) without escaping special character,\nturn this parameter on. It is not enabled by default.\n" }, { "name": "-NormalizeBlock", "content": "Takes a subroutine reference as parameter and gets the current block or blockname passed\nas parameter and is expected to return it in some altered way as a scalar string. The\nsub will be called before anything else will be done by the module itself (e.g.\ninterpolation).\n\nExample:\n\n-NormalizeBlock => sub { my $x = shift; $x =~ s/\\s*$//; $x; }\n\nThis removes trailing whitespaces of block names.\n" }, { "name": "-NormalizeOption", "content": "Same as -NormalizeBlock but applied on options only.\n" }, { "name": "-NormalizeValue", "content": "Same as -NormalizeBlock but applied on values only.\n" }, { "name": "getall", "content": "Returns a hash structure which represents the whole config.\n" }, { "name": "files", "content": "Returns a list of all files read in.\n" }, { "name": "save_file", "content": "Writes the config hash back to the hard disk. This method takes one or two parameters. The\nfirst parameter must be the filename where the config should be written to. The second\nparameter is optional, it must be a reference to a hash structure, if you set it. If you do\nnot supply this second parameter then the internal config hash, which has already been\nparsed, will be used.\n\nPlease note that any occurrence of comments will be ignored by getall() and thus be lost\nafter you call this method.\n\nYou need also to know that named blocks will be converted to nested blocks (which is the\nsame from the perl point of view). An example:\n\n\nid 13\n\n\nwill become the following after saving:\n\n\n\nid 13\n\n\n\nExample:\n\n$confobj->savefile(\"newrcfile\", \\%config);\n\nor, if the config has already been parsed, or if it didn't change:\n\n$confobj->savefile(\"newrcfile\");\n" }, { "name": "save_string", "content": "This method is equivalent to the previous savefile(), but it does not store the generated\nconfig to a file. Instead it returns it as a string, which you can save yourself afterwards.\n\nIt takes one optional parameter, which must be a reference to a hash structure. If you omit\nthis parameter, the internal config hash, which has already been parsed, will be used.\n\nExample:\n\nmy $content = $confobj->savestring(\\%config);\n\nor:\n\nmy $content = $confobj->savestring();\n" } ] }, "CONFIG FILE FORMAT": { "content": "Lines beginning with # and empty lines will be ignored. (see section COMMENTS!) Spaces at the\nbeginning and the end of a line will also be ignored as well as tabulators. If you need spaces\nat the end or the beginning of a value you can surround it with double quotes. An option line\nstarts with its name followed by a value. An equal sign is optional. Some possible examples:\n\nuser max\nuser = max\nuser max\n\nIf there are more than one statements with the same name, it will create an array instead of a\nscalar. See the example below.\n\nThe method getall returns a hash of all values.\n", "subsections": [] }, "BLOCKS": { "content": "You can define a block of options. A block looks much like a block in the wellknown Apache\nconfig format. It starts with and ends with .\n\nA block start and end cannot be on the same line.\n\nAn example:\n\n\nhost = muli\nuser = moare\ndbname = modb\ndbpass = D4r9Iu\n\n\nBlocks can also be nested. Here is a more complicated example:\n\nuser = hans\nserver = mc200\ndb = maxis\npasswd = D3rf$\n\nuser = tom\ndb = unknown\nhost = mila\n\nindex int(100000)\nname char(100)\nprename char(100)\ncity char(100)\nstatus int(10)\nallowed moses\nallowed ingram\nallowed joice\n\n\n\nThe hash which the method getall returns look like that:\n\nprint Data::Dumper(\\%hash);\n$VAR1 = {\n'passwd' => 'D3rf$',\n'jonas' => {\n'tablestructure' => {\n'prename' => 'char(100)',\n'index' => 'int(100000)',\n'city' => 'char(100)',\n'name' => 'char(100)',\n'status' => 'int(10)',\n'allowed' => [\n'moses',\n'ingram',\n'joice',\n]\n},\n'host' => 'mila',\n'db' => 'unknown',\n'user' => 'tom'\n},\n'db' => 'maxis',\n'server' => 'mc200',\n'user' => 'hans'\n};\n\nIf you have turned on -LowerCaseNames (see new()) then blocks as in the following example:\n\n\n\nOwner root\n\n\n\nwould produce the following hash structure:\n\n$VAR1 = {\n'dir' => {\n'attributes' => {\n'owner' => \"root\",\n}\n}\n};\n\nAs you can see, the keys inside the config hash are normalized.\n\nPlease note, that the above config block would result in a valid hash structure, even if\n-LowerCaseNames is not set! This is because *Config::General* does not use the block names to\ncheck if a block ends, instead it uses an internal state counter, which indicates a block end.\n\nIf the module cannot find an end-block statement, then this block will be ignored.\n", "subsections": [] }, "NAMED BLOCKS": { "content": "If you need multiple blocks of the same name, then you have to name every block. This works much\nlike Apache config. If the module finds a named block, it will create a hashref with the left\npart of the named block as the key containing one or more hashrefs with the right part of the\nblock as key containing everything inside the block(which may again be nested!). As examples\nsays more than words:\n\n# given the following sample Limit Deny Options ExecCgi Index\n Limit DenyAll Options None \n\n# you will get:\n\n$VAR1 = {\n'Directory' => {\n'/usr/frik' => {\n'Options' => 'None',\n'Limit' => 'DenyAll'\n},\n'/usr/frisco' => {\n'Options' => 'ExecCgi Index',\n'Limit' => 'Deny'\n}\n}\n};\n\nYou cannot have more than one named block with the same name because it will be stored in a\nhashref and therefore be overwritten if a block occurs once more.\n", "subsections": [] }, "WHITESPACE IN BLOCKS": { "content": "The normal behavior of Config::General is to look for whitespace in block names to decide if\nit's a named block or just a simple block.\n\nSometimes you may need blocknames which have whitespace in their names.\n\nWith named blocks this is no problem, as the module only looks for the first whitespace:\n\n\n\n\nwould be parsed to:\n\n$VAR1 = {\n'person' => {\n'hugo gera' => {\n},\n}\n};\n\nThe problem occurs, if you want to have a simple block containing whitespace:\n\n\n\n\nThis would be parsed as a named block, which is not what you wanted. In this very case you may\nuse quotation marks to indicate that it is not a named block:\n\n<\"hugo gera\">\n\n\nThe save() method of the module inserts automatically quotation marks in such cases.\n", "subsections": [] }, "EXPLICIT EMPTY BLOCKS": { "content": "Beside the notation of blocks mentioned above it is possible to use explicit empty blocks.\n\nNormally you would write this in your config to define an empty block:\n\n\n\n\nTo save writing you can also write:\n\n\n\nwhich is the very same as above. This works for normal blocks and for named blocks.\n\nIDENTICAL OPTIONS (ARRAYS)\nYou may have more than one line of the same option with different values. Example:\n\nlog log1\nlog log2\nlog log2\n\nYou will get a scalar if the option occurred only once or an array if it occurred more than\nonce. If you expect multiple identical options, then you may need to check if an option occurred\nmore than once:\n\n$allowed = $hash{jonas}->{tablestructure}->{allowed};\nif (ref($allowed) eq \"ARRAY\") {\n@ALLOWED = @{$allowed};\nelse {\n@ALLOWED = ($allowed);\n}\n}\n\nThe same applies to blocks and named blocks too (they are described in more detail below). For\nexample, if you have the following config:\n\n\nuser max\n\n\nuser hannes\n\n\nthen you would end up with a data structure like this:\n\n$VAR1 = {\n'dir' => {\n'blah' => [\n{\n'user' => 'max'\n},\n{\n'user' => 'hannes'\n}\n]\n}\n};\n\nAs you can see, the two identical blocks are stored in a hash which contains an", "subsections": [ { "name": "array", "content": "Under some rare conditions you might not want this behavior with blocks (and named blocks too).\nIf you want to get one single hash with the contents of both identical blocks, then you need to\nturn the new() parameter -MergeDuplicateBlocks on (see above). The parsed structure of the\nexample above would then look like this:\n\n$VAR1 = {\n'dir' => {\n'blah' => {\n'user' => [\n'max',\n'hannes'\n]\n}\n}\n};\n\nAs you can see, there is only one hash \"dir->{blah}\" containing multiple \"user\" entries. As you\ncan also see, turning on -MergeDuplicateBlocks does not affect scalar options (i.e. \"option =\nvalue\"). In fact you can tune merging of duplicate blocks and options independent from each\nother.\n\nIf you don't want to allow more than one identical options, you may turn it off by setting the\nflag *AllowMultiOptions* in the new() method to \"no\". If turned off, Config::General will\ncomplain about multiple occurring options with identical names!\n\nFORCE SINGLE VALUE ARRAYS\nYou may also force a single config line to get parsed into an array by turning on the option\n-ForceArray and by surrounding the value of the config entry by []. Example:\n\nhostlist = [ foo.bar ]\n\nWill be a singlevalue array entry if the option is turned on. If you want it to remain to be an\narray you have to turn on -ForceArray during save too.\n" } ] }, "LONG LINES": { "content": "If you have a config value, which is too long and would take more than one line, you can break\nit into multiple lines by using the backslash character at the end of the line. The\nConfig::General module will concatenate those lines to one single-value.\n\nExample:\n\ncommand = cat /var/log/secure/tripwire | \\\nmail C<-s> \"report from tripwire\" \\\nhoney@myotherhost.nl\n\ncommand will become: \"cat /var/log/secure/tripwire | mail \"-s\" 'report from twire'\nhoney@myotherhost.nl\"\n", "subsections": [] }, "HERE DOCUMENTS": { "content": "You can also define a config value as a so called \"here-document\". You must tell the module an\nidentifier which indicates the end of a here document. An identifier must follow a \"<<\".\n\nExample:\n\nmessage <>\n\nIf you turned on -UseApacheInclude (see new()), then you can also use the following statement to\ninclude an external file:\n\ninclude externalconfig.rc\n\nThis file will be inserted at the position where it was found as if the contents of this file\nwere directly at this position.\n\nYou can also recursively include files, so an included file may include another one and so on.\nBeware that you do not recursively load the same file, you will end with an error message like\n\"too many open files in system!\".\n\nBy default included files with a relative pathname will be opened from within the current\nworking directory. Under some circumstances it maybe possible to open included files from the\ndirectory, where the configfile resides. You need to turn on the option -IncludeRelative (see", "subsections": [ { "name": "new", "content": "my $conf = Config::General(\n-ConfigFile => \"/etc/crypt.d/server.cfg\"\n-IncludeRelative => 1\n);\n\n/etc/crypt.d/server.cfg:\n\n<>\n\nIn this example Config::General will try to include *acl.cfg* from */etc/crypt.d*:\n\n/etc/crypt.d/acl.cfg\n\nThe default behavior (if -IncludeRelative is not set!) will be to open just *acl.cfg*, wherever\nit is, i.e. if you did a chdir(\"/usr/local/etc\"), then Config::General will include:\n\n/usr/local/etc/acl.cfg\n\nInclude statements can be case insensitive (added in version 1.25).\n\nInclude statements will be ignored within C-Comments and here-documents.\n\nBy default, a config file will only be included the first time it is referenced. If you wish to\ninclude a file in multiple places, set /-IncludeAgain to true. But be warned: this may lead to\ninfinite loops, so make sure, you're not including the same file from within itself!\n\nExample:\n\n# main.cfg\n\nclass=Some::Class\n\ninclude printers.cfg\n\n# ...\n\n\nclass=Another::Class\n\ninclude printers.cfg\n\n# ...\n\n\nNow \"printers.cfg\" will be include in both the \"billy\" and \"bob\" objects.\n\nYou will have to be careful to not recursively include a file. Behaviour in this case is\nundefined.\n" } ] }, "COMMENTS": { "content": "A comment starts with the number sign #, there can be any number of spaces and/or tab stops in\nfront of the #.\n\nA comment can also occur after a config statement. Example:\n\nusername = max # this is the comment\n\nIf you want to comment out a large block you can use C-style comments. A /* signals the begin of\na comment block and the */ signals the end of the comment block. Example:\n\nuser = max # valid option\ndb = tothemax\n/*\nuser = andors\ndb = toand\n*/\n\nIn this example the second options of user and db will be ignored. Please beware of the fact, if\nthe Module finds a /* string which is the start of a comment block, but no matching end block,\nit will ignore the whole rest of the config file!\n\nNOTE: If you require the # character (number sign) to remain in the option value, then you can\nuse a backslash in front of it, to escape it. Example:\n\nbgcolor = \\#ffffcc\n\nIn this example the value of $config{bgcolor} will be \"#ffffcc\", Config::General will not treat\nthe number sign as the begin of a comment because of the leading backslash.\n\nInside here-documents escaping of number signs is NOT required!\n", "subsections": [] }, "PARSER PLUGINS": { "content": "You can alter the behavior of the parser by supplying closures which will be called on certain\nhooks during config file processing and parsing.\n\nThe general aproach works like this:\n\nsub ck {\nmy($file, $base) = @;\nprint \"open() tries $file ... \";\nif ($file =~ /blah/) {\nprint \"ignored\\n\";\nreturn (0);\n} else {\nprint \"allowed\\n\";\nreturn (1, @);\n}\n}\n\nmy %c = ParseConfig(\n-IncludeGlob => 1,\n-UseApacheInclude => 1,\n-ConfigFile => shift,\n-Plug => { preopen => *ck }\n);\n\nOutput:\n\nopen() tries cfg ... allowed\nopen() tries x/*.conf ... allowed\nopen() tries x/1.conf ... allowed\nopen() tries x/2.conf ... allowed\nopen() tries x/blah.conf ... ignored\n\nAs you can see, we wrote a little sub which takes a filename and a base directory as parameters.\nWe tell Config::General via the Plug parameter of new() to call this sub everytime before it\nattempts to open a file.\n\nGeneral processing continues as usual if the first value of the returned array is true. The\nsecond value of that array depends on the kind of hook being called.\n\nThe following hooks are available so far:\n\npreopen\nTakes two parameters: filename and basedirectory.\n\nHas to return an array consisting of 3 values:\n\n- 1 or 0 (continue processing or not)\n- filename\n- base directory\n\npreread\nTakes two parameters: the filehandle of the file to be read and an array containing the raw\ncontents of said file.\n\nThis hook will be applied in read(). File contents are already available at this stage,\ncomments will be removed, here-docs normalized and the like. This hook gets the unaltered,\noriginal contents.\n\nHas to return an array of 3 values:\n\n- 1 or 0 (continue processing or not)\n- the filehandle\n- an array of strings\n\nYou can use this hook to apply your own normalizations or whatever.\n\nBe careful when returning the abort value (1st value of returned array 0), since in this\ncase nothing else would be done on the contents. If it still contains comments or something,\nthey will be parsed as legal config options.\n\npostread\nTakes one parameter: a reference to an array containing the prepared config lines (after\nbeing processed by read()).\n\nThis hook will be applied in read() when everything else has been done.\n\nHas to return an array of 2 values:\n\n- 1 or 0 (continue processing or not) [Ignored for post hooks]\n- a reference to an array containing the config lines\n\npreparsevalue\nTakes 2 parameters: an option name and its value.\n\nThis hook will be applied in parsevalue() before any processing.\n\nHas to return an array of 3 values:\n\n- 1 or 0 (continue processing or not)\n- option name\n- value of the option\n\npostparsevalue\nAlmost identical to preparsevalue, but will be applied after parsevalue() is finished\nand all usual processing and normalization is done.\n\nNot implemented yet: hooks for variable interpolation and block parsing.\n", "subsections": [] }, "OBJECT ORIENTED INTERFACE": { "content": "There is a way to access a parsed config the OO-way. Use the module Config::General::Extended,\nwhich is supplied with the Config::General distribution.\n", "subsections": [] }, "VARIABLE INTERPOLATION": { "content": "You can use variables inside your config files if you like. To do that you have to use the\nmodule Config::General::Interpolated, which is supplied with the Config::General distribution.\n", "subsections": [] }, "EXPORTED FUNCTIONS": { "content": "Config::General exports some functions too, which makes it somewhat easier to use it, if you\nlike this.\n\nHow to import the functions:\n\nuse Config::General qw(ParseConfig SaveConfig SaveConfigString);\n\nParseConfig()\nThis function takes exactly all those parameters, which are allowed to the new() method of\nthe standard interface.\n\nExample:\n\nuse Config::General qw(ParseConfig);\nmy %config = ParseConfig(-ConfigFile => \"rcfile\", -AutoTrue => 1);\n\nSaveConfig()\nThis function requires two arguments, a filename and a reference to a hash structure.\n\nExample:\n\nuse Config::General qw(SaveConfig);\n..\nSaveConfig(\"rcfile\", \\%somehash);\n\nSaveConfigString()\nThis function requires a reference to a config hash as parameter. It generates a\nconfiguration based on this hash as the object-interface method savestring() does.\n\nExample:\n\nuse Config::General qw(ParseConfig SaveConfigString);\nmy %config = ParseConfig(-ConfigFile => \"rcfile\");\n.. # change %config something\nmy $content = SaveConfigString(\\%config);\n", "subsections": [] }, "CONFIGURATION AND ENVIRONMENT": { "content": "No environment variables will be used.\n", "subsections": [] }, "SEE ALSO": { "content": "I recommend you to read the following documents, which are supplied with Perl:\n\nperlreftut Perl references short introduction\nperlref Perl references, the rest of the story\nperldsc Perl data structures intro\nperllol Perl data structures: arrays of arrays\n\nConfig::General::Extended Object oriented interface to parsed configs\nConfig::General::Interpolated Allows one to use variables inside config files\n", "subsections": [] }, "LICENSE AND COPYRIGHT": { "content": "Copyright (c) 2000-2016 Thomas Linden\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] }, "BUGS AND LIMITATIONS": { "content": "See rt.cpan.org for current bugs, if any.\n", "subsections": [] }, "INCOMPATIBILITIES": { "content": "None known.\n", "subsections": [] }, "DIAGNOSTICS": { "content": "To debug Config::General use the Perl debugger, see perldebug.\n", "subsections": [] }, "DEPENDENCIES": { "content": "Config::General depends on the modules FileHandle, File::Spec::Functions, File::Glob, which all\nare shipped with Perl.\n", "subsections": [] }, "AUTHOR": { "content": "Thomas Linden \n", "subsections": [] }, "VERSION": { "content": "2.63\n", "subsections": [] } } } }