### Modifiers

To build a new name you surely want to use a variable but you need to change its value. For example : change its case, delete some characters, switch parts, modify the format of a date ...

Modifiers are the tools that will achieve this.

Different class exists :

- Case modifiers
- Character modifiers (conversion)
- String modifier : "[ ]"
- String modifier : "( )"
  - Extraction
  - Replacement
  - Regular expression
  - Transliteration
- Date modifier
- Modifiers specific to some variables
- Group renaming

Note : In the text below, the string delimiter used is `"` (quotation mark). In fact, you can use `"` or `'` (apostrophe). The starting and ending delimiters must be the same.

#### Case modifiers

Case modifiers are specified just after the `'%'` of the variable :

`u` | all characters upper-case
`l` | all characters lower-case
`U` | first character of each word upper-case, the others lower-case. The words are separated by the characters specified in "Preferences/New name computation/Word separator characters".
`L` | first character upper-case, the rest lower-case

For example, for the file `"Ébölie family photo.JPG"` :

> `

> Expression | Result
> %uf | ÉBÖLIE FAMILY PHOTO.JPG
> %lf | ébölie family photo.jpg
> %Uf | Ébölie Family Photo.jpg
> %Lf | Ébölie family photo.jpg

> `

In "Preferences/New name computation/Force case" it is possible to define a list of words with a specific case that you want to use. This applies only to variables content therefore not to free text. Two modifiers enable to force or prevent to use this feature directly in the expression :

`+` | force it
`-` | prevent it

If `"FamilY"` is part of the words with a case to force :

> `

> Expression | Result
> %+f | Ébölie FamilY photo.JPG
> %+uf | ÉBÖLIE FamilY PHOTO.JPG
> %-uf | ÉBÖLIE FAMILY PHOTO.JPG

> `

#### Character modifiers (conversion)

These modifiers are represented by a letter following the `'%'` of the variable :

`@` | Conversion of accented characters to standard ASCII ('é' → 'e', 'ü' → 'u', 'Á' → 'A' ...) For example, for the file `"Ébölie family photo.JPG"` : `
Expression | Result
%@f | Ebolie family photo.JPG
%@uf | EBOLIE FAMILY PHOTO.JPG
%@Lf | Ebolie family photo.jpg
`
`#` | Conversion of '%XX' characters You may have noticed that sometimes file names can contain hexadecimal sequences starting with a `'%'`. They generally appear after a transfert between systems that do not suppport the same character set. This modifier will try to convert these sequences. Examples : `
Content of %f | %#f
bb%41cc.txt | bbAcc.txt
%C2ccented.txt | Âccented.txt
%C3%A9l%C3%A8ve.jpg | élève.jpg
%D8%AE%D9%86%D9%81%D8%B3%D8%A7%D8%A1.png | خرحبا.png
%FF%FE%41%00%2E%00%74%00%78%00%74%00 | A.txt
`
`&` | Conversion of UTF8-ascii characters to UTF8 You may also have noticed sequences like the ones below. They generally appear because of a wrong interpretation of UTF8 encoded characters. This modifier will try to convert them. Examples : `
Content of %f | %&f
Ã©lÃ¨ve.jpg | élève.jpg
TyÃ¶pÃ¶ytÃ¤.jpg | Työpöytä.jpg
Ø®Ù†ÙØ³Ø§Ø¡.png | خرحبا.png
`

#### String modifier : "[ ]"

Every variable can be postfixed by a `"[]"` modifier.

It will be split into an array of substrings following the specified separator characters.
The usage is : `[ i, n, "s" ]`

> `i` | index of the substring to extract If "0" (zero), the complete string is returned without the beginning and ending spaces If negative, the extraction is done from the end
> `n` | number of elements to extract starting at the ith one, optional If "0" (zero), the extraction is done until the end of the string If negative, the number of elements to extract is computed from the end of the string 1 is the default value
> `s` | list of separator characters, optional If it is not specified, the list defined in "Preferences/New name computation/Array elements separators" is used

If the chosen string is `"%b"`, `"%b[n]"` contains the file base name characters between the n-1 and nth separator occurrences. Beginning and ending spaces are deleted (full trim).

For example, on the file :
`"01 - Artist_Group - Song title .mp3"`
with `"-"` in "Preferences/New name computation/Array elements separators" :

> `

> Expression | Result
> %b[3].%e | Song title.mp3
> %ub[3] - %b[2].%e | SONG TITLE - Artist_Group.mp3
> %b[1,2].%e | 01 - Artist_Group.mp3
> %b[1].%e | 01.mp3
> %b[-3].%e | 01.mp3
> %b[-1].%e | Song title.mp3
> %b[0] | 01 - Artist_Group - Song title
> %b[2,"_"] | Group - Song title
> %b[2][2,"_"] | Group
> %b[2,0].%e | Artist_Group - Song title.mp3
> %b[1,-1].%e | 01 - Artist_Group.mp3
> %b[2,2,"t"] | ist_Group - Song

> `

#### String modifier : "( )"

Every variable can be postfixed by a `"()"` modifier.

This modifier can have several functions :

- String extraction

  The usage is very near of the standard "substr" : `( p, n )`

  `p` | starting position If negative, it is relative to the end of the string
  `n` | number of characters If "0" (zero) or not specified, the extraction is done until the end If negative, the number of characters to extract is computed from the end of the string

  Here are some examples using the file `"autoexec.bat"` :

  `

  Expression | Result
  %b(1,4).%e | auto.bat
  %b(5).%e | exec.bat
  %ub(5,2).%e(1,1) | EX.b
  %b(-4,3).bat | exe.bat
  %b(1,-4).bat | auto.bat
  %b(-4,-2).bat | ex.bat
  %b(4,-2).bat | ex.bat

  `
- String replacement

  The usage is near of the standard "replace" : `( "s1", "s2", s, n, c )`

  `s1` | string to replace
  `s2` | replacement string If it is not specified, the string to replace is deleted
  `s` | starting occurrence If negative, it is relative to the end of the string
  `n` | number of replacements to do If negative, all remaining occurrences are treated
  `c` | number indicating if the search is case sensitive : 0 (zero) for no, any other value for yes

  The last four parameters are optional.
  By default all occurrences are treated and the search is case insensitive.

  Here are some examples using the file `"autoexec.bat"` :

  `

  Expression | Result
  %b("auto","automatic").%e | automaticexec.bat
  %b("exe").%e | autoc.bat
  %b("e","#",2,1).%e | autoex#c.bat
  %b("e","#",-1).%e | autoex#c.bat
  %b("e","#",1,1).%e | auto#xec.bat
  %b("e","#",-2,1).%e | auto#xec.bat
  %b("E","#",1,-1).%e | auto#x#c.bat
  %b("E","#",1,-1,0).%e | auto#x#c.bat
  %b("e",,,,1).* | autoxc.bat

  `
- Modification by regular expression

  The usage is near of the standard : `(s/exp/fmt/mod)`

  `s` | the `'s'` is a constant, it has to be present
  `exp` | regular expression
  `fmt` | replacement format
  `mod` | modifiers
  `g` | treat all occurrences
  `i` | case insensitive search

  You can find details about the syntax in the wxWidgets online documentation (http://docs.wxwidgets.org/trunk/overview_resyntax.html).
  (Siren uses the ARE flavour)

  Here are some examples using the file `"autoexec.bat"` :

  `

  Expression | Result
  %b(s/[AE]/#/i).%e | #utoexec.bat
  %b(s/[AE]/#/gi).%e | #uto#x#c.bat
  %b(s/(.{4})(....)/\2 - \1/).%e | exec - auto.bat

  `
- Modification by transliteration

  This modifier can replace one character with another, remove some and delete duplicates.
  It is based on the standard commands `"tr"` and `"y"`.

  The usage is near of the standard : `(tr/s/r/mod)`

  `tr` | `"tr"` is a constant, it has to be present
  `s` | the characters to search for. Intervals can be specified, for example : `A-Z0-1`
  `r` | the replacement characters. Intervals can be specified here too.
  `mod` | modifiers
  `c` | invert (complement) the search
  `d` | delete characters that are present in the search list but without correspondance in the replacement list. Without this option they are simply copied.
  `s` | remove duplicates

  The replacements are done based on the character positions in the lists.
  For example, using the file : `"a video file.avi"`

  `

  %b(tr/aeiouy/AEIOUY/).%e | gives | A vIdEO fIlE.txt

  `
  `'e'` is at the second position in the search list. It is replaced by the second character of the replacement list : `'E'`.
  For intervals the principle is the same except that the position takes their length into account.

  Here are some examples using the same file :

  `

  Expression | Result
  %b(tr/a-f/1-6/).%e | 1 vi45o 6il5.avi
  %b(tr/a-f/ABCDEF/).%e | A viDEo FilE.avi
  %b(tr/avideofl/4√1∂30∫7/).%e | 4 √1∂30 ∫173.avi
  %b(tr/aeiouy/-/c).%e | a--i-eo--i-e.avi
  %b(tr/aeiouy/#/d).%e | # vd fl.avi
  %b(tr/idfl/@@@@/s).%e | a v@eo @e.avi

  `

#### Date modifier

In Siren, the default date/time format is `YYYYMMDD_HHMMSS`.

By postfixing a "date" variable with a `"{}"` modifier (opening and closing braces) it is possible to specify the format to use and change its value. For more details about its syntax, consult the dedicated help page.

The usage is : `{ "f", t }`

- `f` : format to use, optional
- `t` : time to add (positive or negative), optional
  It follows a "hms" format. Only the hours (h), minutes (m) and seconds (s) can be specified.
  It must not be surrounded by quotes.
  For example : 12s , -1h51m , +6h5m40s ...

#### Modifiers specific to some variables

It is possible to modify the presentation and the value of some specific variables :

- Either directly in the expression inside a `"{}"` modifier (braces). This modifier must immediately follow the name of the variable.
- Either permanently in "Preferences/New name computation/Numbers" (except for the `%NNx` variables).

Here is the a list of these variables with the description of their dedicated modifier.

For the selection numbers : `%n`, `%np`, `%nc`, `%ncs`, `%ncf` and `%ncfs`
the usage is : `{ p, s, i }`

- `p` : size (a size set to 1 avoids any addition of zeros on the left)
- `s` : start
- `i` : step

For the numbers contained in the base file name : `%N`, `%N1`, `%N2` ...
the usage is : `{ p, v, n }`

- `p` : size (a size set to 1 avoids any addition of zeros on the left)
- `v` : value to add (positive or negative)
- `n` : position of the number to extract
  If negative, the extraction is done from the end

For the non numeric strings contained in the base file name : `%NN`, `%NN1`, `%NN2` ...
the usage is : `{ n }`

- `n` : position of the string to extract
  If negative, the extraction is done from the end

For the number of selected files : `%ns` and for the track numbers: `%mT`, `%AT` and `%An`
the usage is : `{ p }`

- `p` : size (a size set to 1 avoids any addition of zeros on the left)

For the length of random strings : `%Rn`, `%Ra` and `%Rs`
the usage is : `{ l }`

- `l` : length

For example (if the default values have not been modified) :

> `

> Expression | Sel Num 1 | Sel Num 2 | Sel Num 3
> Img_%n{2}.jpg | Img_01.jpg | Img_02.jpg | Img_03.jpg
> Img_%n{2,10}.jpg | Img_10.jpg | Img_11.jpg | Img_12.jpg
> Img_%n{2,10,5}.jpg | Img_10.jpg | Img_15.jpg | Img_20.jpg

> `

For `Fic2_15zzz784.txt` :

> `

> %N{4,0,1} | gives | 0002
> %N{4,0,-1} | gives | 0784
> %NN{-1} | gives | zzz

> `

#### Group renaming

By default a variable content always belongs to the file currently treated. This modifier allows to change this behaviour and use the information from another file of the "group" it belongs to.
A group is a number of consecutively selected files.

This modifier must be specified immediately after the `'%'`.

The usage is : `< p, i >`

- `p` : group size
- `i` : file indice in the group (from 1 to group size), optional
  1 is the default value

It only applies to the variable it is associated to.

Here are a few examples based on files named : `aaa.doc`, `aaa1.pdf`, `dcmt.doc`, `dcmt-two.pdf` and selected following the same order :

> `

> Expression | aaa.doc | aaa1.pdf | dcmt.doc | dcmt-two.pdf
> %<2,1>b.%e | aaa.doc | aaa.pdf | dcmt.doc | dcmt.pdf
> %<2,2>b.%e | aaa1.doc | aaa1.pdf | dcmt-two.doc | dcmt-two.pdf
> %<2,1>ub(1,2).%ue | AA.DOC | AA.PDF | DC.DOC | DC.PDF
> %b.%<2,1>e | aaa.doc | aaa1.doc | dcmt.doc | dcmt-two.doc
> %<2,1>b-%<4,4>b[2].%e | aaa-two.pdf | aaa-two.pdf | dcmt-two.pdf | dcmt-two.pdf

> `

A detailed example can be found here

.