# replace

## Description

Replace a pattern from a file

## Parameters

file
  Description: File to be processed.

  Domain: Valid filename pointing to existing file

  Default: -

to_file
  Description: File to save replacement's result to. If not defined `file' is used as `to_file' value.

  Domain: Valid filename

  Default: -

to_directory
  Description: Directory to which file(s)'s result should be saved to

  Domain: Valid directoryname pointing to existing directory

  Default: -

match
  Description: Regular expressions defining the pattern to be replaced by

  Domain: valid regular expression

  Default: -

token
  Description: Text to be replaced by

  Domain: -

  Default: -

variable_pattern
  Description: Replace all occurencies of Geant variables

  Domain: a string that contains a single underscore '_', which is replaced by the variable name

  Default: -

replace
  Description: Replace `match' or `token' entities by this value. This value can use regexp patterns such as \1\.

  Domain: -

  Default: -

flags
  Description: Flags to precise match replacement (g: global, i: caseless; m: multiline; s: singeline)

  Domain: string composed by g, i, m or s.

  Default: non global, non caseless and singleline-

## RNG Specification

      <define name="replace">
        <element name="replace">
          <ref name="dir_if_unless"/>
          <choice>
            <group>
              <attribute name="file"/>
            </group>
            <group>
              <attribute name="file"/>
              <attribute name="to_file"/>
            </group>
            <group>
              <attribute name="file"/>
              <attribute name="to_directory"/>
            </group>
            <group>
              <attribute name="to_directory"/>
              <ref name="fileset"/>
            </group>
          </choice>
    	  <choice>
    		  <group>
    			<attribute name="token" />
    			<attribute name="replace" />
    		  </group>
    		  <group>
    			<attribute name="match" />
    			<attribute name="replace" />
    		  </group>
    		  <group>
    			<attribute name="variable_pattern" />
    		  </group>
          </choice>
          <optional>
    		<attribute name="flags" />
          </optional>
        </element>
      </define>

## Examples

      <replace file="test.txt" to_file="new_test.txt" token="foo" replace="BAR" flags="gi" />
      <replace file="new_test.txt" match="([0-9]+)" replace="NUM(\1\)" flags="gi" />
      <replace file="new_test.txt" match="((.)\2)" replace="[\1\]" flags="gi"  />
      <replace dir="${cwd}" token="123" replace="321" flags="g" >
    	  <fileset include="@(**/*.txt)" />
      </replace>
      <replace file="in.txt" to_file="out.txt" variable_pattern="${_}"/>