|
Usage
|
| krefslc3 pref-file pref-var |
| The krefslc3 program was written in order to read variables from preference files. |
| In the earliest days of boxenv, all of the customisation variables were stored among the environment variables. It kept on that way, until eventually it became apparent that this would eventually result in the environment being cluttered. |
| The solution was to implement a tree of preference files. Now, the Environment Variables would only store a few essential customization elements, including the location of the Main Preference File, and the whole tree of Preference Files would store everything else needed. Everything, save only a few essentials, resides most of the time in the preference files and is only loaded into Environment Varibles when needed. |
| In boxenv 3, the preference files traditionally end in ".prf3", the environment variable that points to the Main Preference File is BX3PREF, and the main program used to load preference variables into the environment is krefslc3. |
| The krefslc3 program accepts two argumengs. The first argument is the name of the preference file being queried. The second argument is the name of the variable being queried. |
| It sends to Standard Output the value of the preference variable, followed by a trailing newline character. The reason for adding the trailing newline character is so that if, for some reason, you decide to call krefslc3 from the command-line, the prompt for your next command will appear in a separate line from krefslc3's output. In other words, the newline character is added for the sake of neatness. |
| If krefslc3 is called from bash, then bash will automatically take care of the newline character when loading the value into the environment. However, the newline character is something you need to be aware of when calling krefslc3 from PERL. But don't distress over this. One call to PERL's chop() function can easily solve this. |
| krefslc3 makes no distinction between a preference variable being empty and a preference variable being absent. It is up to the program calling krefslc3 to realize that an empty line as the return value is an indication that the preference variable was not found. |
| All this being said, the rest of this documentation shall be devoted to describing the structure of a preference file. |
| As was noted earlier, preference files in boxenv 3 are supposed to end in ".prf3", though that is not enforced by boxenv or by krefslc3. |
| Each preference file is divided into lines, which are separated from each other by newline characters. It is imortant that it be like this, as a Un*x text-file. If you try using one saved like a Macintosh or a DOS text-file, that could cause problems. |
| Each line in the preference file is divided into any number of parts, which are separated by colons (":"). A line can have any number of parts: though it must have at least two parts to be of any meaning at all. |
| A line must never begin with a colon, but it is recommended that each line end with one, for the sake of neatness. |
| The first part of a line in the preference file (which does not have any preceeding colons, and begins at the very beginning of the line) is called the identifier. The second part is called the directive. Any and all parts of the line after that are called arguments. |
| The identifier is simply the name of the preference variable that this line applies to: nothing more and nothing less. What krefslc3 does is start at the beginning of the preference file with an empty buffer, and processes each line who's identifier matches the environment variable being queried. By the time krefslc3 reaches the end of the preference file, this buffer (known as the Variable Buffer) will have the value that krefslc3 will need to output. |
| The directive, which is the second part of the line, says what kind of operation krefslc3 needs to do at the point of the identifier matches the preference variable being queried. |
| All parts of the line after that are the arguments. Depending on what the directive is, they may or may not be needed. |
| That's it as for the basics of the preference file's structure. All that needs to be discussed from here on is the various directives and their meanings. |
| clear: (uses no arguments) |
| If the directive is "clear" then krefslc3 will clear the Variable Buffer: i.e., erase whatever is in it and set it to be empty. |
| col: (uses one argument) |
| If the directive is "col", then the First Argument should be a positive integer. krefslc3 will add that number of colons onto the end of the Variable Buffer. |
| env: (uses one argument) |
| If the directive is "env" then krefslc3 will add the value of the environment variable named in the First Argument onto the end of the Variable Buffer. |
| One word of caution: don't use the environment variables ARGV_A, ARGV_B, and ARGV_C, as they could cause conflict with the implementation of the "rec" directive. |
| http: (uses one argument) |
| If the directive is "http" was implemented to make it easier to specify a variable that is a URL on the web. The first thing it does is add the actual string, "http", onto the end of the Variable Buffer. Then, it adds one colon onto the end of the Variable Buffer. Third and last, it adds the contents of the First Argument onto the end of the Variable Buffer. |
| lit: (uses one argument) |
| If the directive is "lit", then all krefslc3 does is add the contents of the First Argument onto the end of the Variable Buffer. |
| qok: (uses no arguments) |
| If the directive is "qok" that tells krefslc3 that if the Variable Buffer is either empty or complete. |
| At this point, if the Variable Buffer is empty (i.e., has nothing in it) then this line is ignored, and krefslc3 goes on. |
| But if the Variable Buffer is non-empty (i.e., has something in it) then krefslc3 produces it's output and quits successfully, as though it had already reached the end of the Preference File. |
| quit: (uses no arguments) |
| If the directive is "quit" then krefslc3 produces it's output and quits successfully, as though it had already reached the end of the Preference File. |
| rec: (uses one argument) |
| If the directive is "rec" then krefslc3 will call another krefslc3 process to query from the current preference file the variable named in the First Argument. Then it will take the value of that variable, and add it onto the end of the Variable Buffer. |
| split: (uses no arguments) |
| If the directive is "split" then "krefslc3" adds a colon onto the end of the Variable Buffer of both of the following conditions are true (and does nothing if either of the following conditions is false). The first condition is that the Variable Buffer must contain something (i.e. be non-empty). The second condition is that the last character currently in the Variable Buffer must be something other than a colon. |