Replaces tokens in the original input with the contents of a file.

The file to be used is controlled by the name of the token which corresponds to the basename of the file to be used together with the optional pre and postfix strings that is possible to set.

By default all HTML entities in the file is replaced by the corresponding HTML entities. This behaviour can be controlled by the "translatehtml" parameter.

Supported parameters are:

     prefix         string Text to be prefixed to token before using as filename
     postfix        string Text to be prefixed to token before using as filename
     dir            string The directory where the files should be read from
     translatehtml  bool   If we should translate all HTML entities in the file.

Example:

author | johan persson, johanp@aditus.nu
version | $Id: 164a2d9eeba3673653086b32e9fa2045168c992c $
access | public
see | \global\ReplaceTokensWithFile
package | phing.filters
copyright | 2003 seasonfive. All rights reserved

### Methods

## Constructor used by Phing's introspection mechanism.

    __construct(\Reader $in)

Inherited

The original filter reader is only used for chaining purposes, never for filtering purposes (and indeed it would be useless for filtering purposes, as it has no real data to filter). ChainedReaderHelper uses this placeholder instance to create a chain of real filters.

inherited_from | \BaseFilterReader::__construct()
inherited_from | \BaseParamFilterReader::__construct()

### Parameters

#### $in

`\Reader`

## Creates a new ReplaceTokensWithFile using the passed in Reader for instantiation.

    chain(\Reader $reader) : object

### Parameters

#### $reader

`object`

A Reader object providing the underlying stream. Must not be `null`.

### Returns

`object`A new filter based on this configuration, but filtering the specified reader

## Close stream.

    close()

Inherited

inherited_from | \FilterReader::close()
inherited_from | \BaseFilterReader::close()
inherited_from | \BaseParamFilterReader::close()

### Exceptions

`\IOException` | if there is an error closing stream

## Returns whether the end of file has been reached with input stream.

    eof() : boolean

Inherited

inherited_from | \BaseFilterReader::eof()
inherited_from | \BaseParamFilterReader::eof()

### Returns

`boolean`

## Returns the "begin token" character.

    getBeginToken() : string

### Returns

`string`The character used to denote the beginning of a token.

## Returns the drectory where to look for the files to use for token replacement

    getDir()

## Returns the "end token" character.

    getEndToken() : \the

### Returns

`\the`character used to denote the beginning of a token

## Returns the initialized status.

    getInitialized() : boolean

Inherited

inherited_from | \BaseFilterReader::getInitialized()
inherited_from | \BaseParamFilterReader::getInitialized()

### Returns

`boolean`whether or not the filter is initialized

## getParameters()

    getParameters()

Inherited

inherited_from | \BaseParamFilterReader::getParameters()

## Returns the postfix that is added to the token in order to create the file name.

    getPostfix()

For example if the token is 01 and the postfix is ".php" then the filename to look for will be "01.php"

## getPrefix()

    getPrefix()

## Returns the project this filter is part of.

    getProject() : object

Inherited

inherited_from | \BaseFilterReader::getProject()
inherited_from | \BaseParamFilterReader::getProject()

### Returns

`object`The project this filter is part of

## Returns the filename, url, etc.

    getResource() : string

Inherited

that is being read from. This is critical for, e.g., ExpatParser's ability to know the filename that is throwing an ExpatParserException, etc.

inherited_from | \FilterReader::getResource()
inherited_from | \BaseFilterReader::getResource()
inherited_from | \BaseParamFilterReader::getResource()

### Returns

`string`

## Returns the drectory where to look for the files to use for token replacement

    getTranslateHTML()

## Convenience method to support logging in filters.

    log(string $msg, int $level)

Inherited

inherited_from | \BaseFilterReader::log()
inherited_from | \BaseParamFilterReader::log()

### Parameters

#### $msg

`string`

Message to log.

#### $level

`int`

Priority level.

## If supported, places a "marker" (like a bookmark) at current stream position.

    mark()

Inherited

A subsequent call to reset() will move stream position back to last marker (if supported).

inherited_from | \Reader::mark()
inherited_from | \FilterReader::mark()
inherited_from | \BaseFilterReader::mark()
inherited_from | \BaseParamFilterReader::mark()

## Whether marking is supported.

    markSupported() : boolean

Inherited

inherited_from | \Reader::markSupported()
inherited_from | \FilterReader::markSupported()
inherited_from | \BaseFilterReader::markSupported()
inherited_from | \BaseParamFilterReader::markSupported()

### Returns

`boolean`

## Returns stream with tokens having been replaced with appropriate values.

    read(\off $len) : mixed

If a replacement value is not found for a token, the token is left in the stream.

### Parameters

#### $len

`\off`

Offset at which to start storing characters.

### Exceptions

`\IOException` | If an I/O error occurs

### Returns

`mixed`filtered stream, -1 on EOF.

## Reads a line of text ending with '\n' (or until the end of the stream).

    readLine() : \the

Inherited

The returned String retains the '\n'.

inherited_from | \BaseFilterReader::readLine()
inherited_from | \BaseParamFilterReader::readLine()

### Exceptions

`\IOException` | if the underlying reader throws one during reading

### Returns

`\the`line read, or `null` if the end of the stream has already been reached

## Is stream ready for reading.

    ready() : boolean

Inherited

inherited_from | \Reader::ready()
inherited_from | \FilterReader::ready()
inherited_from | \BaseFilterReader::ready()
inherited_from | \BaseParamFilterReader::ready()

### Returns

`boolean`

## Reset the current position in stream to beginning or last mark (if supported).

    reset()

Inherited

inherited_from | \FilterReader::reset()
inherited_from | \BaseFilterReader::reset()
inherited_from | \BaseParamFilterReader::reset()

## Sets the "begin token" character.

    setBeginToken(string $beginToken)

### Parameters

#### $beginToken

`string`

the character used to denote the beginning of a token.

## Sets the drectory where to look for the files to use for token replacement

    setDir(string $dir)

### Parameters

#### $dir

`string`

## Sets the "end token" character.

    setEndToken(string $endToken)

### Parameters

#### $endToken

`string`

the character used to denote the end of a token

## Sets the initialized status.

    setInitialized(boolean $initialized)

Inherited

inherited_from | \BaseFilterReader::setInitialized()
inherited_from | \BaseParamFilterReader::setInitialized()

### Parameters

#### $initialized

`boolean`

Whether or not the filter is initialized.

## setParameters()

    setParameters($parameters)

Inherited

inherited_from | \BaseParamFilterReader::setParameters()

### Parameters

#### $parameters

## Sets the postfix that is added to the token in order to create the file name.

    setPostfix(string $postfix)

For example if the token is 01 and the postfix is ".php" then the filename to look for will be "01.php"

### Parameters

#### $postfix

`string`

## Sets the prefix that is prepended to the token in order to create the file name.

    setPrefix(string $prefix)

For example if the token is 01 and the prefix is "example" then the filename to look for will be "example01"

### Parameters

#### $prefix

`string`

## Sets the project to work with.

    setProject(\Project $project)

Inherited

inherited_from | \BaseFilterReader::setProject()
inherited_from | \BaseParamFilterReader::setProject()

### Parameters

#### $project

`object`

The project this filter is part of. Should not be `null`.

## setReader()

    setReader(\Reader $in)

Inherited

inherited_from | \FilterReader::setReader()
inherited_from | \BaseFilterReader::setReader()
inherited_from | \BaseParamFilterReader::setReader()

### Parameters

#### $in

## Sets the drectory where to look for the files to use for token replacement

    setTranslateHTML($translate)

### Parameters

#### $translate

## Move stream position relative to current pos.

    skip(int $n)

Inherited

inherited_from | \FilterReader::skip()
inherited_from | \BaseFilterReader::skip()
inherited_from | \BaseParamFilterReader::skip()

### Parameters

#### $n

`int`

## Initializes parameters This method is only called when this filter is used through a <filterreader> tag in build file.

    _initialize()

## Replace the token found with the appropriate file contents

    replaceTokenCallback(array $matches) : string

access | private

### Parameters

#### $matches

`array`

Array of 1 el containing key to search for.

### Returns

`string`Text with which to replace key or value of key if none is found.

### Properties

##

    $_parameters

Inherited

inherited_from | \BaseParamFilterReader::$$_parameters

##

    $in : \Reader

Inherited

inherited_from | \FilterReader::$$in
inherited_from | \BaseFilterReader::$$in
inherited_from | \BaseParamFilterReader::$$in

##

    $initialized

Inherited

inherited_from | \BaseFilterReader::$$initialized
inherited_from | \BaseParamFilterReader::$$initialized

##

    $project

Inherited

inherited_from | \BaseFilterReader::$$project
inherited_from | \BaseParamFilterReader::$$project

##

    $_beginToken : string

##

    $_dir : string

The default is to look in the current file.

##

    $_endToken : string

##

    $_postfix : string

##

    $_prefix : string

##

    $_tokensources : array

##

    $_translatehtml : boolean

For example all '<' will be translated to < before the content is inserted.

### Constants

## Default "begin token" character.

    DEFAULT_BEGIN_TOKEN : string

## Default "end token" character.

    DEFAULT_END_TOKEN : string