User Manual
Regular Expressions
Regular expressions are a common method used for processing text files and allows complex pattern matching. In addition to this, values within the regular expression search pattern can then be used in the replace syntax to allow for the results to be transformed. Keep in mind that Regular Expressions look complex, but follow a standard definition across nearly all computer platforms. You can learn more about regular expressions here.
Let's break down an example of a regular expression used to find all bracketed chords in a song. We would type something like this into the OnSong search field:
/\[(.*?)\]/i
Denoting Patterns
First, we use the forward slashes to denote the regular expression. This means that this contains two pieces of information, the regular expression and the modifiers. In this example we have [(.*?)] as the regular expression pattern and i as the modifier.
Escaping Text
Regular expressions are a large topic in and of itself, but it involves typing specific characters to match specific characters. In the example above, the first backslash character is used to "escape" the character that follows. This is because square brackets have a special meaning in regular expressions to find ranges of characters. We add backslash in front of these so they are treated like ordinary characters.
Match Groups
You'll see that what's contained in the square brackets is surrounded in parenthesis. Parenthesis in regular expressions are used to denote groups. We place the main pattern parenthesis because we are going to use that match in our replace field.
Pattern
Inside of the parenthesis, we have a period .. This denotes a character of any kind. This is because we want to find square brackets that contains something. Next, we see an asterisk *****. This tells the pattern that we want to find zero or more of the preceding match. In this case, we want to find any number of characters. The question mark ? in this context creates what is called a "non-greedy search". In essence we don't want to find everything between brackets because this would gobble up our whole song! We just want to find things until we get to an ending bracket.
Modifers
These are placed after the forward slashes and changes how the regular expression matching behaves. Each character represents a different modifier. You can combine these as needed:
- i makes the search case-insensitive. Any part of the pattern that involves character case will basically be ignored.
- x allows whitespaces and comments to be included in the regular expression.
- s allows the "." dot pattern match to also match line separators. By default, regular expressions are matched line by line.
- m determines how the "^" and "$" pattern match characters perform. By default, these represent the start and end of the input, but setting this modifier will allow them to match the start and end of each line.
- w determines the method used for evaluating word boundaries. If set, OnSong will determine words based on Unicode UAX 29 text boundaries.
In summary, this will find anything between two square brackets in a non-greedy fashion, and make that match available for replacement.
Replacement
You could use simple text-based replacement for your search. For instance, to remove all chords from a song, use the above pattern and replace with nothing. However, you can also use the match group you've made to sound the chords with something else. For instance, you could type the following into the OnSong replace field:
<$!>
This would take the pattern that was matched between the brackets and place it within angle brackets instead.
