{
"content": [
{
"type": "text",
"text": "# Config::General::Extended (perldoc)\n\n## NAME\n\nConfig::General::Extended - Extended access to Config files\n\n## SYNOPSIS\n\nuse Config::General;\n$conf = Config::General->new(\n-ConfigFile => 'configfile',\n-ExtendedAccess => 1\n);\n\n## DESCRIPTION\n\nThis is an internal module which makes it possible to use object oriented methods to access\nparts of your config file.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS** (10 subsections)\n- **AUTOLOAD METHODS** (1 subsections)\n- **COPYRIGHT**\n- **BUGS**\n- **AUTHOR**\n- **VERSION**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
}
],
"structuredContent": {
"command": "Config::General::Extended",
"section": "",
"mode": "perldoc",
"summary": "Config::General::Extended - Extended access to Config files",
"synopsis": "use Config::General;\n$conf = Config::General->new(\n-ConfigFile => 'configfile',\n-ExtendedAccess => 1\n);",
"tldr_summary": null,
"tldr_examples": [],
"tldr_source": null,
"flags": [],
"examples": [],
"see_also": [],
"section_outline": [
{
"name": "NAME",
"lines": 2,
"subsections": []
},
{
"name": "SYNOPSIS",
"lines": 7,
"subsections": []
},
{
"name": "DESCRIPTION",
"lines": 5,
"subsections": []
},
{
"name": "METHODS",
"lines": 1,
"subsections": [
{
"name": "configfile",
"lines": 3
},
{
"name": "obj",
"lines": 75
},
{
"name": "hash",
"lines": 9
},
{
"name": "array",
"lines": 8
},
{
"name": "value",
"lines": 20
},
{
"name": "is_hash",
"lines": 17
},
{
"name": "exists",
"lines": 2
},
{
"name": "keys",
"lines": 10
},
{
"name": "delete",
"lines": 3
},
{
"name": "find",
"lines": 18
}
]
},
{
"name": "AUTOLOAD METHODS",
"lines": 30,
"subsections": [
{
"name": "value",
"lines": 2
}
]
},
{
"name": "COPYRIGHT",
"lines": 5,
"subsections": []
},
{
"name": "BUGS",
"lines": 2,
"subsections": []
},
{
"name": "AUTHOR",
"lines": 2,
"subsections": []
},
{
"name": "VERSION",
"lines": 2,
"subsections": []
}
],
"sections": {
"NAME": {
"content": "Config::General::Extended - Extended access to Config files\n",
"subsections": []
},
"SYNOPSIS": {
"content": "use Config::General;\n\n$conf = Config::General->new(\n-ConfigFile => 'configfile',\n-ExtendedAccess => 1\n);\n",
"subsections": []
},
"DESCRIPTION": {
"content": "This is an internal module which makes it possible to use object oriented methods to access\nparts of your config file.\n\nNormally you don't call it directly.\n",
"subsections": []
},
"METHODS": {
"content": "",
"subsections": [
{
"name": "configfile",
"content": "Set the filename to be used by save to \"filename\". It returns the current configured\nfilename if called without arguments.\n"
},
{
"name": "obj",
"content": "Returns a new object (of Config::General::Extended Class) from the given key. Short example:\nAssume you have the following config:\n\n\n\nage 23\n\n\nage 56\n\n\n\nblah blubber\nblah gobble\nleer\n\n\nand already read it in using Config::General::Extended::new(), then you can get a new object\nfrom the \"individual\" block this way:\n\n$individual = $conf->obj(\"individual\");\n\nNow if you call getall on *$individual* (just for reference) you would get:\n\n$VAR1 = (\nmartin => { age => 13 }\n);\n\nOr, here is another use:\n\nmy $individual = $conf->obj(\"individual\");\nforeach my $person ($conf->keys(\"individual\")) {\n$man = $individual->obj($person);\nprint \"$person is \" . $man->value(\"age\") . \" years old\\n\";\n}\n\nSee the discussion on hash() and value() below.\n\nIf the key from which you want to create a new object is empty, an empty object will be\nreturned. If you run the following on the above config:\n\n$obj = $conf->obj(\"other\")->obj(\"leer\");\n\nThen $obj will be empty, just like if you have had run this:\n\n$obj = Config::General::Extended->new( () );\n\nRead operations on this empty object will return nothing or even fail. But you can use an\nempty object for *creating* a new config using write operations, i.e.:\n\n$obj->someoption(\"value\");\n\nSee the discussion on AUTOLOAD METHODS below.\n\nIf the key points to a list of hashes, a list of objects will be returned. Given the\nfollowing example config:\n\n\n\n\nyou could write code like this to access the list the OOP way:\n\nmy $objlist = $conf->obj(\"option\");\nforeach my $option (@{$objlist}) {\nprint $option->name;\n}\n\nPlease note that the list will be returned as a reference to an array.\n\nEmpty elements or non-hash elements of the list, if any, will be skipped.\n"
},
{
"name": "hash",
"content": "This method returns a hash(if it is one!) from the config which is referenced by \"key\".\nGiven the sample config above you would get:\n\nmy %subhash = $conf->hash(\"individual\");\nprint Dumper(\\%subhash);\n$VAR1 = {\nmartin => { age => 13 }\n};\n"
},
{
"name": "array",
"content": "This the equivalent of hash() mentioned above, except that it returns an array. Again, we\nuse the sample config mentioned above:\n\n$other = $conf->obj(\"other\");\nmy @blahs = $other->array(\"blah\");\nprint Dumper(\\@blahs);\n$VAR1 = [ \"blubber\", \"gobble\" ];\n"
},
{
"name": "value",
"content": "This method returns the scalar value of a given key. Given the following sample config:\n\nname = arthur\nage = 23\n\nyou could do something like that:\n\nprint $conf->value(\"name\") . \" is \" . $conf->value(\"age\") . \" years old\\n\";\n\nYou can use this method also to set the value of \"key\" to something if you give over a hash\nreference, array reference or a scalar in addition to the key. An example:\n\n$conf->value(\"key\", \\%somehash);\n# or\n$conf->value(\"key\", \\@somearray);\n# or\n$conf->value(\"key\", $somescalar);\n\nPlease note, that this method does not complain about existing values within \"key\"!\n"
},
{
"name": "is_hash",
"content": "As seen above, you can access parts of your current config using hash, array or scalar\nmethods. But you are right if you guess, that this might become problematic, if for example\nyou call hash() on a key which is in real not a hash but a scalar. Under normal\ncircumstances perl would refuse this and die.\n\nTo avoid such behavior you can use one of the methods ishash() isarray() isscalar() to\ncheck if the value of \"key\" is really what you expect it to be.\n\nAn example(based on the config example from above):\n\nif($conf->ishash(\"individual\") {\n$individual = $conf->obj(\"individual\");\n}\nelse {\ndie \"You need to configure a \"individual\" block!\\n\";\n}\n"
},
{
"name": "exists",
"content": "This method returns just true if the given key exists in the config.\n"
},
{
"name": "keys",
"content": "Returns an array of the keys under the specified \"key\". If you use the example config above\nyou could do that:\n\nprint Dumper($conf->keys(\"individual\");\n$VAR1 = [ \"martin\", \"joseph\" ];\n\nIf no key name was supplied, then the keys of the object itself will be returned.\n\nYou can use this method in foreach loops as seen in an example above(obj() ).\n"
},
{
"name": "delete",
"content": "This method removes the given key and all associated data from the internal hash structure.\nIf 'key' contained data, then this data will be returned, otherwise undef will be returned.\n"
},
{
"name": "find",
"content": "Given a list of nodes, ->find will search for a tree that branches in just this way,\nreturning the Config::General::Extended object it finds at the bottom if it exists. You can\nalso search partway down the tree and ->find should return where you left off.\n\nFor example, given the values find (qw (A B C)) and the following tree ( tags omitted\nfor brevity):\n\n\n\n...\n\n\n...\n\nBAR = shoo\n\nfind() will find the object at *C* with the value BAR = shoo and return it.\n"
}
]
},
"AUTOLOAD METHODS": {
"content": "Another useful feature is implemented in this class using the AUTOLOAD feature of perl. If you\nknow the keynames of a block within your config, you can access to the values of each individual\nkey using the method notation. See the following example and you will get it:\n\nWe assume the following config:\n\n\nname = Moser\nprename = Peter\nbirth = 12.10.1972\n\n\nNow we read it in and process it:\n\nmy $conf = Config::General::Extended->new(\"configfile\");\nmy $person = $conf->obj(\"person\");\nprint $person->prename . \" \" . $person->name . \" is \" . $person->age . \" years old\\n\";\n\nThis notation supports only scalar values! You need to make sure, that the block does\nnot contain any subblock or multiple identical options(which will become an array after\nparsing)!\n\nIf you access a non-existent key this way, Config::General will croak an error. You can turn\nthis behavior off by setting -StrictObjects to 0 or \"no\". In this case undef will be returned.\n\nOf course you can use this kind of methods for writing data too:\n\n$person->name(\"Neustein\");\n\nThis changes the value of the \"name\" key to \"Neustein\". This feature behaves exactly like",
"subsections": [
{
"name": "value",
"content": "under the given key will be overwritten.\n"
}
]
},
"COPYRIGHT": {
"content": "Copyright (c) 2000-2014 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": {
"content": "none known yet.\n",
"subsections": []
},
"AUTHOR": {
"content": "Thomas Linden \n",
"subsections": []
},
"VERSION": {
"content": "2.07\n",
"subsections": []
}
}
}
}