# Python functions

## Introduction

In Bakefile, the expression inside `$(...)` doesn't have to be a variable name, it can be any Python expression. Expressions that cannot be evaluated at runtime and are translated into output format conditions are more limited, but as long as the expression is evaluated only at Bakefile execution time, it can be any valid Python expression. In particular, any Python functions may be called.

In order to make common tasks easier, Bakefile provides miscellaneous utility functions which can be used in your bakefiles. Unlike tags and rules provided through modules, the functions documented in this section are available everywhere in Bakefile.

Except where explicitely stated differently, all functions accept as arguments Python strings.

## How to use a Python function in a bakefile

Python instructions and thus also Python calls to functions, can be used in bakefile wrapping them into the `$( )` symbols. E.g. suppose you want to use the function described below to set variable `A`; you should then write:

    <set var="A">
        $(fileList('mypath/*.c'))
    </set>

## Python functions

The following Python functions are defined:

### envvar

    envvar("name")

Returns reference to environment variable `name`. This function should be used instead of `$(DOLLAR)(name)` idiom, because some output formats (namely, Watcom makefiles) use different syntax for referencing environment variables.

### isconst

    isconst(expr)

Returns `true` if the expression (i.e. not variable name as in the case of etc.) given as argument is constant expression.

### isdefined

    isdefined(name)

Returns `true` if the given string is the name of an option or a (conditional) variable previously defined in the bakefile.

### isoption

    isoption(name)

Returns `true` if the given string is the name of an option previously defined in the bakefile.

### iscondvar

    iscondvar(name)

Returns `true` if the given string is the name of a conditional variable previously defined in the bakefile.

### ifthenelse

    ifthenelse(cond, iftrue, iffalse)

Allows to write if-then-else constructs inside bakefiles. The arguments are respectively the if condition (use Python syntax!), the Python expression to execute in case the condition results true and the Python expression to execute in case the condition results false.

### ref

    ref(var, target=None)

Creates a reference to the given var variable which will be evaluated only in the final stage of bakefile processing.

### isDeadTarget

    isDeadTarget(target)

Returns true if the given string is the name of a conditional target whose condition is never met.

### substituteFromDict

    substituteFromDict(var, dict, desc=None)

Returns the value of the dictionary entry whose key matches the value of the variable or option named var. E.g.

    <set var="A">
        $(substituteFromDict(OPTION,{'1':'value1','0':'value0'}))
    </set>

sets A to value1 if OPTION is 1 or to value2 if OPTION is 0. Note that Python requires curly brackets to define a dictionary.

### nativePaths

    nativePaths(filenames)

Returns the given string with the `/` characters substituted by the content of the variable (see the Variables section).

### addPrefixIfNotEmpty

    addPrefixIfNotEmpty(prefix, value)

Returns the value string prefixed with prefix, unless value is empty.

### addPrefixToList

    addPrefixToList(prefix, value)

Adds prefix to every item in value interpreted as whitespace-separated list. E.g.

    <set var="A">
        $(addPrefixToList('file','1.txt 2.txt 3.txt'))
    </set>

sets the A variable to `file1.txt file2.txt file3.txt`

### safeSplit

    safeSplit(str)

Splits the given string like the built-in split() Python function but, unlike the Python `split()` function, recognizes that an expression like

    "$(myPythonFuncCall(arg1, arg2)) item2"

must be split as

    [ "$(myPythonFuncCall(arg1, arg2))", "item2" ]

and not as the built-in split() function would do

    [ "$(myPythonFuncCall(arg1,", "arg2))", "item2" ]

### fileList

    fileList(path)

Returns a string containing a space-separed list of all files found in the given path. path typically is a relative path (absolute paths should be avoided in well-designed bakefiles) with a mask used to match only wanted files.

When the given path is relative, it must be relative to the global variable; remember that is in turn relative to the location of the generated makefile (see ).

Additionally this function can accept Python lists of strings, too. The returned value is the list of all files found in all the paths of the list. E.g.

    <sources>$(fileList('../src/*.cpp'))</sources>
    <sources>$(fileList(['../src/*.cpp', '../src/*.c']))</sources>

### removeDuplicates

    removeDuplicates(list)

Returns a copy of the given (space-separed) list with all duplicate tokens removed.