{
    "content": [
        {
            "type": "text",
            "text": "# AppConfig::File (perldoc)\n\n## NAME\n\nAppConfig::File - Perl5 module for reading configuration files.\n\n## SYNOPSIS\n\nuse AppConfig::File;\nmy $state   = AppConfig::State->new(\\%cfg1);\nmy $cfgfile = AppConfig::File->new($state, $file);\n$cfgfile->parse($file);            # read config file\n\n## DESCRIPTION\n\nUSING THE AppConfig::File MODULE\nTo import and use the AppConfig::File module the following line should appear in your Perl\nscript:\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **OVERVIEW**\n- **DESCRIPTION** (1 subsections)\n- **AUTHOR**\n- **COPYRIGHT**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "AppConfig::File",
        "section": "",
        "mode": "perldoc",
        "summary": "AppConfig::File - Perl5 module for reading configuration files.",
        "synopsis": "use AppConfig::File;\nmy $state   = AppConfig::State->new(\\%cfg1);\nmy $cfgfile = AppConfig::File->new($state, $file);\n$cfgfile->parse($file);            # read config file",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [
            {
                "flag": "",
                "long": null,
                "arg": null,
                "description": "+debug Variable, environment variable and tilde (home directory) expansions Variable values may contain references to other AppConfig variables, environment variables and/or users' home directories. These will be expanded depending on the EXPAND value for each variable or the GLOBAL EXPAND value. Three different expansion types may be applied: bin = ~/bin # expand '~' to home dir if EXPANDUID tmp = ~abw/tmp # as above, but home dir for user 'abw' perl = $bin/perl # expand value of 'bin' variable if EXPANDVAR ripl = $(bin)/ripl # as above with explicit parens home = ${HOME} # expand HOME environment var if EXPANDENV See AppConfig::State for more information on expanding variable values. The configuration files may have variables arranged in blocks. A block header, consisting of the block name in square brackets, introduces a configuration block. The block name and an underscore are then prefixed to the names of all variables subsequently referenced in that block. The block continues until the next block definition or to the end of the current file. [block1] foo = 10 # block1foo = 10 [block2] foo = 20 # block2foo = 20"
            }
        ],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "OVERVIEW",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 134,
                "subsections": [
                    {
                        "name": "-verbose",
                        "lines": 30
                    }
                ]
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "AppConfig::File - Perl5 module for reading configuration files.\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use AppConfig::File;\n\nmy $state   = AppConfig::State->new(\\%cfg1);\nmy $cfgfile = AppConfig::File->new($state, $file);\n\n$cfgfile->parse($file);            # read config file\n",
                "subsections": []
            },
            "OVERVIEW": {
                "content": "AppConfig::File is a Perl5 module which reads configuration files and use the contents therein\nto update variable values in an AppConfig::State object.\n\nAppConfig::File is distributed as part of the AppConfig bundle.\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "USING THE AppConfig::File MODULE\nTo import and use the AppConfig::File module the following line should appear in your Perl\nscript:\n\nuse AppConfig::File;\n\nAppConfig::File is used automatically if you use the AppConfig module and create an\nAppConfig::File object through the file() method.\n\nAppConfig::File is implemented using object-oriented methods. A new AppConfig::File object is\ncreated and initialised using the AppConfig::File->new() method. This returns a reference to a\nnew AppConfig::File object. A reference to an AppConfig::State object should be passed in as the\nfirst parameter:\n\nmy $state   = AppConfig::State->new();\nmy $cfgfile = AppConfig::File->new($state);\n\nThis will create and return a reference to a new AppConfig::File object.\n\nREADING CONFIGURATION FILES\nThe \"parse()\" method is used to read a configuration file and have the contents update the STATE\naccordingly.\n\n$cfgfile->parse($file);\n\nMultiple files maye be specified and will be read in turn.\n\n$cfgfile->parse($file1, $file2, $file3);\n\nThe method will return an undef value if it encounters any errors opening the files. It will\nreturn immediately without processing any further files. By default, the PEDANTIC option in the\nAppConfig::State object, $self->{ STATE }, is turned off and any parsing errors (invalid\nvariables, unvalidated values, etc) will generated warnings, but not cause the method to return.\nHaving processed all files, the method will return 1 if all files were processed without warning\nor 0 if one or more warnings were raised. When the PEDANTIC option is turned on, the method\ngenerates a warning and immediately returns a value of 0 as soon as it encounters any parsing\nerror.\n\nVariables values in the configuration files may be expanded depending on the value of their\nEXPAND option, as determined from the App::State object. See AppConfig::State for more\ninformation on variable expansion.\n\nCONFIGURATION FILE FORMAT\nA configuration file may contain blank lines and comments which are ignored. Comments begin with\na '#' as the first character on a line or following one or more whitespace tokens, and continue\nto the end of the line.\n\n# this is a comment\nfoo = bar               # so is this\nurl = index.html#hello  # this too, but not the '#welcome'\n\nNotice how the '#welcome' part of the URL is not treated as a comment because a whitespace\ncharacter doesn't precede it.\n\nLong lines can be continued onto the next line by ending the first line with a '\\'.\n\ncallsign = alpha bravo camel delta echo foxtrot golf hipowls \\\nindia juliet kilo llama mike november oscar papa  \\\nquebec romeo sierra tango umbrella victor whiskey \\\nx-ray yankee zebra\n\nVariables that are simple flags and do not expect an argument (ARGCOUNT = ARGCOUNTNONE) can be\nspecified without any value. They will be set with the value 1, with any value explicitly\nspecified (except \"0\" and \"off\") being ignored. The variable may also be specified with a \"no\"\nprefix to implicitly set the variable to 0.\n\nverbose                              # on  (1)\nverbose = 1                          # on  (1)\nverbose = 0                          # off (0)\nverbose off                          # off (0)\nverbose on                           # on  (1)\nverbose mumble                       # on  (1)\nnoverbose                            # off (0)\n\nVariables that expect an argument (ARGCOUNT = ARGCOUNTONE) will be set to whatever follows the\nvariable name, up to the end of the current line. An equals sign may be inserted between the\nvariable and value for clarity.\n\nroom = /home/kitchen\nroom   /home/bedroom\n\nEach subsequent re-definition of the variable value overwrites the previous value.\n\nprint $config->room();               # prints \"/home/bedroom\"\n\nVariables may be defined to accept multiple values (ARGCOUNT = ARGCOUNTLIST). Each subsequent\ndefinition of the variable adds the value to the list of previously set values for the variable.\n\ndrink = coffee\ndrink = tea\n\nA reference to a list of values is returned when the variable is requested.\n\nmy $beverages = $config->drinks();\nprint join(\", \", @$beverages);      # prints \"coffee, tea\"\n\nVariables may also be defined as hash lists (ARGCOUNT = ARGCOUNTHASH). Each subsequent\ndefinition creates a new key and value in the hash array.\n\nalias l=\"ls -CF\"\nalias h=\"history\"\n\nA reference to the hash is returned when the variable is requested.\n\nmy $aliases = $config->alias();\nforeach my $k (keys %$aliases) {\nprint \"$k => $aliases->{ $k }\\n\";\n}\n\nA large chunk of text can be defined using Perl's \"heredoc\" quoting style.\n\nscalar = <<BOUNDARYSTRING\nline 1\nline 2: Space/linebreaks within a HERE document are kept.\nline 3: The last linebreak (\\n) is stripped.\nBOUNDARYSTRING\n\nhash   key1 = <<'FOO'\n* Quotes (['\"]) around the boundary string are simply ignored.\n* Whether the variables in HERE document are expanded depends on\nthe EXPAND option of the variable or global setting.\nFOO\n\nhash = key2 = <<\"bar\"\nText within HERE document are kept as is.\n# comments are treated as a normal text.\nThe same applies to line continuation. \\\nbar\n\nNote that you cannot use HERE document as a key in a hash or a name of a variable.\n\nThe '-' prefix can be used to reset a variable to its default value and the '+' prefix can be\nused to set it to 1\n",
                "subsections": [
                    {
                        "name": "-verbose",
                        "content": "+debug\n\nVariable, environment variable and tilde (home directory) expansions Variable values may contain\nreferences to other AppConfig variables, environment variables and/or users' home directories.\nThese will be expanded depending on the EXPAND value for each variable or the GLOBAL EXPAND\nvalue.\n\nThree different expansion types may be applied:\n\nbin = ~/bin          # expand '~' to home dir if EXPANDUID\ntmp = ~abw/tmp       # as above, but home dir for user 'abw'\n\nperl = $bin/perl     # expand value of 'bin' variable if EXPANDVAR\nripl = $(bin)/ripl   # as above with explicit parens\n\nhome = ${HOME}       # expand HOME environment var if EXPANDENV\n\nSee AppConfig::State for more information on expanding variable values.\n\nThe configuration files may have variables arranged in blocks. A block header, consisting of the\nblock name in square brackets, introduces a configuration block. The block name and an\nunderscore are then prefixed to the names of all variables subsequently referenced in that\nblock. The block continues until the next block definition or to the end of the current file.\n\n[block1]\nfoo = 10             # block1foo = 10\n\n[block2]\nfoo = 20             # block2foo = 20\n"
                    }
                ]
            },
            "AUTHOR": {
                "content": "Andy Wardley, <abw@wardley.org>\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "Copyright (C) 1997-2007 Andy Wardley. All Rights Reserved.\n\nThis module is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "AppConfig, AppConfig::State\n",
                "subsections": []
            }
        }
    }
}