Page Blocks

Hosting sponsored by:

Point In Space

 

API: Cnfg

Filename:
fwpCnfg_loadPairs.ctag

Released With:
5.0.0

Current Version:
1.3.0

Status: Active

Min Lasso Tested: 8.1.0

Max Lasso Tested: 8.5.3

Related:

fwpCnfg_loadFile

fwpCnfg_loadLines

fwpCnfg_LoadVars

Still don't get it?

Check out the talk list archives, or join and ask your questions.

Documentation Error or Request?

Email documentation corrections or comments

API Reference

fwpCnfg_loadPairs (Tag)

Description

Loads a configuration file which is structured with each line being a separate declaration of a first=second pair. The line endings are normalized, empty and comment elements are removed, and the data is then split to become a Lasso array of pairs data type.

The tag searches the /site/configs/ folder and the current /_resources/configs/ folder. Alternately, a full file pathname can be given to load a specific file not in the usual /configs/ folder.

This tag is essentially a macro for the sequence of tags fwpCnfg_loadFile, fwpCnfg_deComment, fwpCnfg_splitLines, and fwpCnfg_splitPairs. The tag can be instructed to despace or not despace files.

Comments in the configuration lines can begin with # or //, empty lines are allowed, and the Lasso container [output_none]...[/output_none] can wrap the file contents. All of these non-data lines will be ignored.

Syntax

fwpCnfg_loadPairs: fileName

Configuration file format:

The default pair definition uses either = or === between the first and second values with no spaces around the =. To allow spaces or tabs around the pair delimiter for config file formatting, use the -removeWhiteSpace parameter.

[output_none]
# comments like this
// or like this
# blank lines allowed too

# the default format 

CA=California
NC=North Carolina

# optional format using -removeWhiteSpace
# to use spaces around the = character

shape       = circle
color       = Candy Apple Red
lineweight  = 1 pt

[/output_none]

Parameters & Member Tags

file (unnamed) = required : either a complete filename with extension or a full pathname. If a file name is specified without any path component, the tag will search the /site/configs/ folder and the current /_resources/configs/ folder. If a file with a path is specified, the complete virtual host root relative path must be specified, and the tag will load that one specific file.

-removeWhiteSpace = optional : if specified, removes spaces and tabs surrounding the = or === of each line, leaving any spaces in the string after the pair delimiter. (Previous -despace param name is deprecated).

-withoutCaching (no value) = optional : add this param to prevent the caching of the config file data. The file is cached prior to final parsing into pairs. The only reason to not have the file cached is if the content is expected to change often, and each call to load it should reload it directly from disk. This would require thread-safe operations by the application to do that. (Previous -nocache param is deprecated).

Examples

fwpCnfg_loadPairs:'custom.cnfg';

fwpCnfg_loadPairs:'custom.cnfg', -removeWhiteSpace;

fwpCnfg_loadPairs:'/nonstandard/config/path/custom.cnfg';

Source Code

View in separate window

<?lassoscript
//............................................................................
//
//    pageblocks: (c) 2002-2007 http://www.pageblocks.org/
//
//............................................................................
/*

    {fileName=        fwpCnfg_loadPairs.ctag }
    {rsrcType=        tag }
    {rsrcName=        fwpCnfg_loadPairs }
    {rsrcHTTP=        www.pageblocks.org/refc/fwpCnfg_loadPairs }

    {lassoVrsnMin=    8.1.0 }
    {lassoVrsnMax=    8.5.3 }

    {author=        Greg Willits }
    {authorEmail=    subscribe to pbTalk at www.pageblocks.org/talk/ }
    {authorHTTP=    www.pageblocks.org }

    {desc=            This tag loads a configuration file,
                    removes comment lines, and 
                    splits the lined into an array of pairs }

    {maintvsrn=        1.3.0 }
    {maintrelease=    5.2.0 }
    {maintdate=        2007-06-09}
    {maintauthor=    Greg Willits }
    {maintnotes=    updated debug and error handling systems,
                     changed some internal vars for better readability }

    {maintvsrn=        1.2.0 }
    {maintrelease=    5.1.0 }
    {maintdate=        2006-05-30}
    {maintauthor=    Greg Willits }
    {maintnotes=    added tagTrace }

    {maintvsrn=        1.1 }
    {maintrelease=    5.0.0 b5 }
    {maintdate=        2006-01-27 }
    {maintauthor=    Greg Willits }
    {maintnotes=    changed some styntax for efficiency,
                    added -despace option,
                    eliminated code used by old RAMbucket caching }

    {maintvsrn=        1.0 }
    {maintrelease=    5.0.0 }
    {maintdate=        2006-01-16 }
    {maintauthor=    Greg Willits }
    {maintnotes=    initial release }

*/
//.............................................................................

define_tag:'fwpCnfg_loadPairs', -priority='replace',
    -required='file',
    -optional='username',
    -optional='password';

//    -removeWhiteSpace (-despace deprecated) 
//    -withoutCaching (-nocache deprecated)

    ($fw_debug >= fw_kChatty) ? $fw_tagTracer->(add:'fwpCnfg_loadPairs', -file = #file);

    local:
        'fileName'             = @#file,
        'withoutCaching'     = false,
        'removeWhiteSpace'     = false,
        'configData'         = string;

//    pull from cache if available
//    else pull from disk (and store to cache)

    #configData = $fw_gConfigCache->(restore:#fileName);

    if: #configData->size > 0;

        // pulled from cache, so nothing else to do

    else;

//    load file data

        (params->find:'-withoutCaching') || (params->find:'-nocache')
            ? #withoutCaching = true;

        (params->find:'-removeWhiteSpace') || (params->find:'-despace')
            ? #removeWhiteSpace = true;

        #configData = (fwpCnfg_loadFile:
            -file        = #fileName,
            -username     = local:'username',
            -password     = local:'password');

//    despace the delimiters

        if: #removeWhiteSpace;
            #configData = (string_replaceRegExp: 
                #configData, 
                -find = '\\s*===\\s*',
                -replace = '===');
            #configData = (string_replaceRegExp: 
                #configData, 
                -find = '\\s*=\\s*',
                -replace = '=');
        /if;

//    convert to array so we can remove comments

        #configData = (fwpCnfg_splitLines: #configData);
        #configData = (fwpCnfg_deComment: #configData);

//    cache or not?
//    cached as an array of pairs

        !#withoutCaching
            ? $fw_gConfigCache->(add:
                -name  = #fileName,
                -value = #configData);

//    make pairs
        #configData = (fwpCnfg_splitPairs: #configData);
    /if;

    return: #configData;

/define_tag;
?>

© 2002-2012, pageblocks.org