Environment Tool (Library) Guideline
This tutorial`s aim is to describe the usage of the environment tool and support the explanation with examples.
Before actually starting I would like to make clear, that there are few possible ways how to use this application:
- An tool runned with script
- A library to your script
- An interactive python session
This tutorial will mostly cover the first usage listed above.
The XML Source File
The most important part you are going to need is the XML file. This is the file that contains the setting you want to use to whatever you are going to do. Your environment is described by variables you want to create and/or modify. To help yourself with maintaining your variables you have the option to use variable as a "local" to define the same for multiple variables and in each individual variable just point to this local. You can use a pointer to another variable if it is not local as well.
You can use two differrent types of variables. List and scalar. List contains sequence of values divided by separator (colon on unix). Scalars are single string variables.
NOTE: You can use Eclipse to work with the XML file by giving the XML schema as a schema for a new XML page. Eclipse then offers visual environment and offers choices and take care about the XML header.
The XML file consists of two parts. The first is the header and then declarations of variables and actions to be taken.
The XML header
The XML header looks as displayed bellow:
<?xml version="1.0" encoding="UTF-8"?>
<env:config xmlns:env="EnvSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="EnvSchema ./EnvSchema.xsd ">
The default namespace you should use is "EnvSchema". In case you would like to use another, you have to change parameters passed by script. You might want to change schema location to correspond to actual file.
Declarations
The second part contains your environment. In order to use a variable you should declera it first. To do that, put the following line to your XML.
<env:declare variable="name" type=
TYPE local=
BOOL] />
This line will create a variable of given name "name" of a type
TYPE ={'list','scalar'} and it will be treated as a local in case local=true and not as a local in case local=false.
In case you will not declera a variable before usage, then it will be treated as an unlocal list variable.
In case variable is redeclared to be any other type than declared before, an error will occur.
NOTE: If you are declaring a variable, that is located in OS its value will be loaded from the system during declaration.
Types
As said before you can use two kinds of varible. Either list or scalar.
TYPE |
DESCRIPTION |
list |
values are separated by separotor depending on OS each individual value is separated by ":" in the XML file every action performed with list is taken for a single value (append), or for each value individualy (remove) |
scalar |
there is only single string value each action is connected to the whole value (append to the end) or to parts (removal of substrings) |
Local Variable and Pointers
When you use a variable as a local it does not change environment of OS in any way. It can be used only as an input to other variables.
You can use both types of variables as locals. If you want to use already defined variable as local you have to use the name of the variable you want to use to value with a $ sign in front. Let`s suppose we want to use our local "myLoc" we worked with before and assign it to "myVar".
<env:append variable="myVar">$myLoc:anotherValue</env:append>
Or you can refer to scalar anywhere in the string. Then use "(" and ")" or "{" and "}".
<env:append variable="myVar">value${myLoc}ToBeExtended</env:append>
List should be referenced only in list as a single value. If refereced in list in the middle of value, exception is raised. If referenced in a scalar, then concateneted version of list is inserted.
Pointers to scalars can appear anywhere.
Actions
After variable is declared you can use action to operate with it. Write the following line in the XML:
<env:
ACTION variable="name">value</env:
ACTION>
where ACTION is one of following:
ACTION |
DESCRIPTION |
append |
add the value(s) to the end of variable |
prepend |
add the value(s) to the begining of variable |
set |
set the value(s) to variable (any other value is lost) |
unset |
delete any value from variable (create an empty one) |
remove |
remove value(s) from the variable |
remove-regexp |
remove according to regular expression given (whole values from lists, substrings from scalars) |
and value is eighter a single string or a list of values separated by ":" for list type of variable.
To append a value "myValue" and "secondValue" to the variable "myVar" the command is:
<env:append variable="myVar">myValue:secondValue</env:variable>
The action parameter can be any of 5 previously listed options.
NOTE: To use drive letter for windows environment please use "[C]" (without quotes) for C: drive (do not put colon next to C - will be added)(like: "[C]\Program Files\")
XML File Operations - Overview
The following table is the overview of possible usage of envRun.py script. Usage of those options is consulted bellow.
option |
short |
description |
--help |
-h |
display help message |
--run COMMAND |
-r |
execute COMMAND |
--output FILE |
-o |
specifies the output file to FILE |
--search NAME |
|
searches file(s) for variable of a given NAME |
--maxdepth INT |
|
sets the maximum depth of nesting for searching to INT |
--ref |
|
turns off listing of references when searching |
--messages LEVEL |
|
set the level of messages to be displayed to LEVEL |
To set new environment for the current session please use
envSetup
To set new environment for newly opened session please use
envTerm
To check the XML file use
envCheck.py
To merge XML files use
envMerge.py
Using the scipt(s) - XML File Operations
Checking the XML file
You can use the tool to validate your XML file. It check for different kinds of conflicts. For example you will receive varining for set or unseting varibable that containes values.
To check your XML file use --check (-c) option:
./envCheck.py YOUR_XML_FILE --check [options]
Merging the XML file
In case you would like to use more than one XML file, you have to merge them first. The result is one XML files made from all files you provided in the order you provided. It can ends with an error if there are inconsistent declarations.
To merge files use --merge (-m) option as following:
./envMerge.py XML_FILES --merge OUTPUT_FILE [options]
Search in the XML file(s)
This functionality allows you to scan XML file(s) for apperance of variable of certain name. It will display a list of apperances sorted in order of aperance in each file and grouped by individual files. Thus you can debug operations, which are taken on individual variable.
./envRun.py YOUR_XML_FILES --search VARIABLE_NAME [options]
By default you will receive a list of all referenced variables, which are mentioned in the search variable, together with searched one. To turn this off, use
--ref switch.
There is a limit of maximum depth of nesting variables and locals (default 5). To modify this limit use
--maxdepth INT.
Using the scipt(s) - Environment Operations
Setting the environment of the current shell
To set new environment for the current session please use
envSetup.
Under LINUX you have to source runscript. First navigate to the folder of this script (make also sure that you have envSetup.py script in your PYTHONPATH) and then use following syntax (with proper modification of "source" (on win none)(replace ".ext" with one according to your OS/shell version))
source ./envSetup.ext YOUR_XML_FILE
Running a command with a specific environment
To run command (or script) use envRun.py python script. Command is parsed the way shell input is parsed and the first part is the command and everything else are parameters for this command.
./envRun.py YOUR_XML_FILE --run COMMAND
Envoking a new terminal window
To envoke a new terminal (command prompt) window please use envTerm. Syntax is following (replace .ext with one according to your OS/shell version):
./envTerm.ext YOUR_XML_FILE
NOTE: This functionality will be supported only if you have gnome-terminal command available.
Using the interactive session
Following chapter is going through the basics of usage of Control class of Env Application
Creating new instance of Environment
From package Control import Environment (if not imported already).
Create new instance (consult script for more options of constructor):
env = Environment([loadFromSystem = True, useAsWriter=False, reportLevel = 1])
Now you can use your environment similary to list. To create new variable "PATH" with value "myPath" use (note that in this case value of PATH will be first loaded from system and your value will be appended - to prevent this pass
loadFromSystem=False to constructor):
env['PATH'] = 'myPath'
By this way of creation you will get a variable, which is list and not local. To get another type, use
declare function first passing on from type={'list','scalar'} and boolean to local.
env.declare(varName, type, local)
You can then use append, print and other list operations.
If you set
useAsWriter=True, every action that changes variables will be recorded to XML instead of execution and then you can produce the XML file by calling
env.finishXMLinput(OUTPUT_FILE). To start new recording again use
env.startXMLInput().
Writing the current state of environment to file
You can write your environment to two different types of files. The first option is to produce shell script, which is able to set the environment to your shell when sourced. To do that use (giving the SCRIPT_TYPE one of "sh", "csh", "bat" parameters):
env.writeToFile(FILE_NAME, SCRIPT_TYPE)
The second option is to produce a XML file with your settings (Please note that there is no track of actions taken to this point, so every variable will be recorder with
set action only. To record all operations taken you have to use
useAsWriter option (see above). To use this functionality do:
env.writeToXMLFile(FILE_NAME)
NOTE: You might want to use the following functions before writing to files:
env.loadAllSystemVariables(),
which load every variable from the system you are running on.
--
MartinPlajner - 26-Aug-2011