vader version info - introduction -what is vader The name is an acronym for Very ADvanced Editing in Renoise. It also sounds cool. Vader. Vader. Yep, it's got a special ring to it. I also kinda wanted to have a V in the start, because I ripped a lot of the main idea from a text editor I like, Vim. 1 basic usage 1.1 BRINGING UP THE COMMAND LINE You can make your first contact with vader by bringing up the command line window. This can be done from the top menus (xxxxxx), or by assigning a keyboard shortcut for 'Open/focus command line' (see xxxxxx), and pressing your shortcut key combination. The command line window, titled vader (version number) should now open. 1.2 GUI OVERVIEW 1.2.1 VISUAL OVERVIEW The command line, when opened, will look like a normal tool window, containing a long textfield that is split in two. The left part, referred afterwards as 'prompt' will display ">>>", indicating the command line is accepting input. When command line window is in 'browse mode', the prompt will display nothing. The command line messages are entered on the right part. Depending on your current settings, the window may additionally display a bigger textfield below the actual command line. This is called the 'home dump'. It is used to display log-type information. The visibility of the home dump can be toggled with a keyboard shortcut. 1.2.2 USAGE CONCEPT: GUI MODES Vader's GUI follows the rules and limitations of a normal renoise tool. The 'command line' for example is nothing more than a textfield element. These rules have been taken as a starting point to implement the overall GUI concept, which is based on two modes; Edit mode and Browse mode. Edit mode is the mode you are in when the textfield is active, and you are editing the command line input. Browse mode is the mode you are in, when the command line window is focused, but the textfield is not. To help distinguish between the two modes, the left part of the command line, aka the prompt shows a ">>>", designating that the edit mode is active. In browse mode the prompt will be empty. In edit mode normal textfield editing functionality applies. You can for example write text, move around with cursor keys, select text and use systemwide copy-paste functions, just like you could on any textfield in renoise. In browse mode, you can control the window with (currently hard-coded) keyboard controls, which allows among other things to browse through the command line history. This browsing gives this mode its name. There's a third possible 'mode', where the command line window is visible, but is not focused. This is not really considered as a mode, because you cannot control the command line in any way, except by focusing it and thus entering edit mode. 1.2.3 ADDITIONAL INTERFACES 1.2.3.1 MACRO GUI 1.2.3.2 SCRIPT EDITOR 1.3 ENTERING SCRIPTS IN COMMAND LINE 1.3.1 ENTERING MESSAGES BY TYPING IN EDIT MODE To enter a command (more specifically a vader script, see xxxx), you first open/focus the command line and by doing so enter edit mode. When the textfield is focused, you type in your command. You can edit your input freely, while still in edit mode. When you're satisfied in the command, approve and send it to renoise by and pressing enter. If you wish to exit edit mode without sending the command (canceling the input), you do so by pressing escape. This all follows normal procedure, when editing any textfield in renoise. This means, that when you cancel a command, the edits you have done are lost. 1.3.2 ENTERING MESSAGES FROM HISTORY IN BROWSE MODE To enter a previously sent command using the command line history, you first open/focus the command line. This puts you in edit mode. Leave edit mode by pressing esc, which then puts you in browse mode. Access command line history with the up and down cursor keys. Pressing up takes you back in history, and pressing down takes you forward. The command line textfield (not focused) will update to show the selected history item. When you've found the right one, enter the selected command by pressing enter while still in browse mode. 1.3.3 REFORMATTING A HISTORY ITEM If you wish to reformat a previously entered command, you can do so by selecting it from the history in browse mode, and then entering edit mode. This will leave the item in command line and focus the textfield, where you can do your editing. When you've done your editing, send the command normally pressing enter in edit mode. One thing to note about editing history items, is that if you start an edit on a history item, and try to enter the _exactly_ same message (i.e. perform no actual editing), the message _will not be entered_. This is due to some limitations in current API, that have yet to be overcome. This is, however a minor inconvenience, and can be diverted by pressing enter a second time, after you have been put to browse mode. 1.3.4 BASIC EXAMPLES t1 l6 t2l2 t1:t2 CTRL+Z t1:2 a:10 a:(a+1) 1.4 BASIC KEYBOARD SHORTCUTS 1.4.1 RENOISE NATIVE SHORTCUTS The vader shortcuts have a dedicated group under the Global -shortcut group. -Global:vader:Open command line... In practice this shortcut works as a general 'enter edit mode' -shortcut. When command line window is not visible, it will open the window and enter edit mode. When command line window is visible and focused (in browse mode), it will enter edit mode. When command line window is visible but not focused, it will focus the window and enter edit mode. -Global:vader:Repeat 1st history item This is a convenience shortcut to repeat the script that is at history position 1 (the latest entered script) again without using the command line window gui. -Global:vader:Repeat 2nd history item This is a convenience shortcut to repeat the script that is at history position 2 without using the command line window gui. -open macro prompt 1.4.2 TOOL INTERNAL SHORTCUTS (COMMAND LINE BROWSE MODE) The tool's internal shortcuts are currently hard-coded. These apply in the command line window, in browse mode. UP move backwards in command line history DOWN move forwards in command line history ENTER enter a message that is displayed in the command line SHIFT+UP toggle home dump visibility debug shortcuts M dump main log in terminal SHIFT+M dump main log in terminal, verbosity 100 D dump debug log in terminal SHIFT+D dump debug log in terminal, verbosity 100 E dump error log in terminal SHIFT+E dump error log in terminal, verbosity 100 H dump history log in terminal SHIFT+H dump history log in terminal, verbosity 100 2 ADVANCED USAGE 2.1 COMMAND LINE SYNTAX OVERVIEW When you type something in the command line and press enter, you are sending a vader script for parsing. A script can contain several messages, separated by a semicolon (;) character. The semicolon is only used to _separate_ messages, and as such it is not necessary to append a semicolon after the last message of a script. For example: "message;message" is a valid script. "message;", ";message", and "message;message;" are considered valid and should parse just fine, but there are superfluous separator characters. The messages in any entered script are executed in order from left to right. Vader syntax is generally NOT based on whitespace as separating element. Whitespace CAN be used to separate elements in order to clarify a message, but in general it is not needed, and will be simply discarded when parsing. This decision is made to ensure efficient typing in of messages. At the moment of writing, vader still can not parse floating point values. These can be entered as equations, though. (e.g. 0.5 = (1/2)) The same applies to negative numbers. (e.g. -10 = (0-10)) 2.2 ANATOMY OF A COMMAND LINE MESSAGE 2.2.1 CONTEXTS OVERVIEW: TARGET, CONTENT, FLAGS A message can be further broken down into 'contexts', which can be thought of asof message parts with a specialized function. All possible contexts are 'target', 'content', 'global flags' and 'macro'. All of these contexts are optional, but usually it doesn't make sense to have a message that doesn't include either a target or a content context. The target and content contexts are essentially what makes vader go. On an abstract level, you could think of them through an analogy of a water hose. The target is the end of the hose you point where you want to spray the water, and the contet is the end of the hose you attach to a wall outlet. Another way to put it would be to say that whatever is in content is applied on target. Another simple way to look at target, is that it moves the cursor. Content could then be seen as the act of 'putting in data' in the current cursor place. This introduction lends to observation that you can move the cursor by entering messages that contain a target context. Likewise you can edit existing data by entering messages that contain a content context. The global flags context further defines some aspects of performing the message. The global flags context applies 'globally' to a single message. (some work in this area yet to be done...) 2.2.2 CONCEPT OF 'SCOPE' The concept of 'scope' is a very important one, when dealing with vader. Basically scope is used to define a portion of song data. The definition of that data follows renoise's internal way of defining song data, and as such, the also the way to define that data in the renoise Lua API. In the API, the song data is accessed through a hierarchical system consisting of patterns, tracks within patterns, lines within tracks, and note- and effect columns within the lines. It's essential to grasp the concept of this (rather simple) hierarchy to understand how command scoping works. Any command involving target or content contexts involve (either directly or indirectly) defined scope. In fact, the target context ONLY consists of a scope definition. Content context can consist of a scope definition or an equation resolvable into a number value. In the latter case, scope is deduced automatically from the target context, or in the case where there is no target, ignored completely. A logical conclusion from all this is that when there is no target context, and the content context is only something resolvable to a number, no song data manipulation can happen, as there is no scope to apply the manipulation. A scope definition consists of a set of 'scope partials'. In a 'full' scope definition each hierarchy level (pattern, track, line, column and sub-column level) has a dedicated scope partial. A scope partial, in turn, consists of a 'scopetag', that defines the hierarchical element referred to (e.g. patterns), and a 'range definition' within that hierarchical level. A simple example would be "t1..6", in which the "t" is the scopetag, defining tracks as the songdata hierarchy level, and "1..6" is the range definition, defining indexes 1 to 6 as the range. The example partial then defines a scope of tracks 1,2,3,4,5 and 6. For a detailed look on scoping techniques, see a dedicated section below. 2.2.3 CONCEPT OR 'ROOT LEVEL' Another important concept when entering messages is the concept of 'root level'. This refers to nesting in the messages. Anything that is not nested within parentheses in a message is considered root level. Especially scopetags have a completely different meaning based on whether they are entered in root level or not. In root level scopetags are considered the 'heads' of scope partials. When they are nested inside parentheses, they are considered to be part of the range definition of a scope partial, having special meaning as such. Considering this, it's usually a good idea to nest complex range definitions inside parentheses. This is not mandatory, however, provided that no scopetags are used in a range definition. To further elaborate this point, the previous example "t1..6" is valid, but could as well be written as "t(1..6)", further differentiating the defined scope partial into the scopetag (or 'head') part and the range definition. On the latter way of defining the scope partial, only the scopetag "t" is at root level. An example in which nesting is mandatory for desired effect, would be "t(1..t)". Here the usage of scopetag as part of the range definition requires the range definition to be nested. If it were not, the "t" within the range definition would be interpret as another 'head' of a scope partial. 2.3 CONTEXTS BROKEN DOWN 2.3.1 TARGET CONTEXT As noted before, target essentially moves the vader cursor into a desired location, for the content part to be applied upon. If there is no content context in the message, the cursor is simply moved with no additional action. The vader cursor is distinguished from actual renoise cursor. For technical reasons, vader must keep an internal cursor position while processing commands, and renoise native cursor cannot be relied on. This allows for a special method of processing data, namely one where the native cursor does not move. By default the renoise native cursor is moved while processing over the target scope. This means that for example when processing all tracks from 1 to " (max), the cursor is left at the last processed track, the last track on song. If this is not the desired behaviour, a " -nomove" (" -nomv" abbreviated) flag appended after the message will tell vader not to move the renoise internal cursor. A " -move" (" -mv" abbreviated) flag will do the opposite. It will specifically instruct the renoise cursor to move with vader cursor. One rather obvious thing to note about defining target, is that while the target scope is multileveled, the actual TARGET, in which the content is directed to, always is the partial that has the lowest defined level, i.e. is the most atomic. -target scope -scope partials -scopetag -range -flags -user variable -content: the stuff to put in target 2.3.2 CONTENT Content is the 'active' part of a message. It defines what is done on target scope. -numeric values -'scope objects' -referencing existing data with 'scope objects' -defining macros -the syntax of defining a macro 2.3.3 SCOPING This section discusses general scoping methods and rules. The concept of scope is discussed in an earlier section, and considered as 'essential basis' for the details below. 2.3.3.1 SCOPE LEVELS Vader messages dealing with song data (patterns, tracks, lines...), rely on scoping. It is the method of defining a range over the song. The basic principle of scope definition is that a scope covers all the hierarchy levels of the song structure, that the user wishes to iterate over. The levels in order of hierarchy are: Pattern level Track level Line level Column level Sub-column level For each of these levels, a set of referencing methods known as scopetags apply. Scopetags are the 'heads' of scope partials. A set of scope partials is a scope definition. The sets for each level, and their scopetags are: PATTERN LEVEL: -Pattern p -Sequence q -Section s TRACK LEVEL: -Track t -Track group g LINE LEVEL: -Line l COLUMN LEVEL: -Note column c -Effect column e SUB COLUMN LEVEL: -Note value n -Instrument value i -Volume value v -Panning value a -Delay value d -Effect number f -Effect amount x NOTES the ones that don't work at the moment are sections and track groups. SCOPETAGS EXPLAINED This section covers the details of scopetags as referencing methods to the song data structure. PATTERN LEVEL Pattern level has three scopetags as methods of referencing the song data. The main ones are pattern- and sequence-scopetags. The section-scopetag can be thought as a sibling to the sequence-scopetag that also includes a predefined range over the order list. (AND IS CURRENTLY NOT IMPLEMENTED!) The main difference of the pattern and sequence scopetags is in the way they relate to the song sequence, the order list. When pattern-scopetag is used, the order list is not considered at all. This means that all edits are done on the pattern currently in the pattern editor. This consequently means that edits will apply to the pattern currently selected in the order list. Additionally, when the -move flag is up, vader will change the current pattern placed in the order list according to the range definition of the pattern scope partial. This method allows iterating over the patterns in song whether they're placed as instances on the order list or not. The range definition will reference to the pattern index numbers. A range of 1..5 defined with a scope partial "p1..5" will include patterns with index numbers 1,2,3,4 and 5. When sequence-scopetag is used, iteration will run over the patterns sequenced in the order list. The range definition will reference to the position indexes in the order list. A range of 1..5 defined in a scope partial "q1..5" will therefore include patterns that are placed in the order list positions 1, 2, 3, 4 and 5 Another big difference between the pattern- and sequence-scopetags is that the sequence scopetag will always create unique pattern instances, when one is needed. So it is not the same thing to reference to current pattern with "p", or the pattern in current sequence position with "q". To elaborate with an example let's assume a song with unique patterns 1 and 2, sequenced in the order list positions 1 to 3 in order 1,1,2. The currently selected order list position is 1, and so the current pattern is also 1. Let's change all panning values of current track into 10. Issuing a command:"ptLa:10" will reference to currently selected pattern, which is pattern number 1. After the command has executed, all patterns with index number 1 are affected. This means patterns in order list positions 1 and 2. The index numbers do not change, i.e. no new pattern instances are created. On the other hand issuing a command:"qtLa:10" will reference to the pattern that is sequenced in the current order list position. Incidentally this is the same pattern, pattern with index number 1. This time the command will create a new pattern with index number 3, and place it on the current order list position. The only affected pattern will be that new one, leaving the original pattern 1 unaffected. A general way to look at the methods is that using the sequence scopetag always relates to the sequenced structure of the song, while the pattern scopetag only relates to the raw pattern data. LEVEL TAG NAME NORMAL DOUBLE UPPER ----------------------------------------------------- PATTERN Pattern p pp P PATTERN Sequence q qq Q PATTERN Section s ss S TRACK LEVEL Track level has two different scopetags; track- and track group -scopetags. Track group -scopetag relates to the track-scopetag much in the same way that the section-scopetag relates to the sequence-scopetag. It predefines a range within the track indexes. (NOTE: TRACK GROUPS SCOPETAG NOT IMPLEMENTED!) LEVEL TAG NAME NORMAL DOUBLE UPPER ----------------------------------------------------- TRACK Track t tt T PATTERN Track group g gg G LINE LEVEL Line level only has one scopetag, the line-scopetag. Range refers to the index number of the line. LEVEL TAG NAME NORMAL DOUBLE UPPER ----------------------------------------------------- LINE Line l ll L SCOPING SHORTHAND 1.SHORTHAND RANGES WITH SCOPETAGS To enter some most useful range definitions, there are some shorthand methods for defining range. This allows to quickly define specific ranges for CURRENT, EACH NON-EMPTY, and EACH AND EVERY item. While the CURRENT range is rarher self-explanatory, the difference between EACH NON-EMPTY and EACH AND EVERY is simply that on the former, all empty songdata items of the referenced kind are skipped over when processing. The main benefit of this is considerable gain in processing speed. -To define CURRENT range with the shorthand, just enter the scopetag with no range definition included. -To define EACH NON-EMPTY range, use a 'double-scopetag', i.e. enter the scopetag twice. -To define EACH AND EVERY range, enter the scopetag in uppercase. examples could include: "PttLCn" EACH AND EVERY pattern, EACH NON-EMPTY track, EACH AND EVERY line, EACH AND EVERY note column, note value "qqTlleex" EACH NON-EMPTY sequence (meaning a sequence position in which there is a pattern that is not empty), EACH AND EVERY track, EACH NON-EMPTY line, EACH NON-EMPTY effect column, effect amount 2.SHORTHAND SCOPE WITH SPARSE SCOPE DEFINITION To avoid entering tediously long scope definitions on every command, vader has ageneral method for deducing what the user must've meant, which is to say, a method to enter scope definitions in shorthand. This is why previous example commands that did not include a full scope worked without errors. Examples of a full scope definition would be (scope partials here separated with whitespace for easier readability): "p1 t1 l1 c1 n", "q1 g1 l1 e1 f", or "s1 t1 l1 c1 i". A full scope definition means that every level of hierarchy is represented as a scope partial. The shorthand rules are based on the hierarchy levels. For each message, vader gets the topmost and lowest hierarchy level explicitly defined in the message. The rules that apply to the automatic scoping with this information are: -Every hierarchy level above the topmost user defined one is automatically scoped with a CURRENT scope. -Every hierarchy level between the topmost and lowest is scoped with a EACH NON-EMPTY scope. -Every hierarchy level below the lowest is ignored in processing, so those are not defined. -On every level that automatic scoping is used, the FIRST of the referencing methods (scopetags) presented in the list above is used. So to elaborate with some examples: "c1" -lowest and topmost defined level is column level -the shorthand written will reference to: current pattern (p), current track (t), current line (l) note column index 1 "l1d" -topmost defined level is line level, lowest defined level is sub-column level -the shorthand written will reference to: current pattern (p), current track (t), line 1, each non-empty note column (n), delay value These rules have been thought over, and seemed to produce a meaningful shorthand syntax. In general, leaving out upper level hierarchy scope partials will refer to the current position, and everything between the topmost defined, and the actual target of editing is brought in scope, if it's not empty. DEFINING VALUES AND RANGES Most functionality in vader requires specifying either values or ranges. A value can be defined in several formats. Defining a decimal integer value is the most straightforward, involving only typing the value in a message. Another typical value format in renoise is hexadecimal value. These can be defined by prepending the value with prefix "0x". As an example; to enter a hexadecimal value AF, type it in as "0xAF". A range is defined by typing in two values separated by the range denominator, which is "..", two points in succession. To define a range that spans from value 10 to value 55, you would enter it as "10..55". On some occasions, such as the ranges in scope partials, the DIRECTION of the range is also meaningful information. The previous example used in a scope partial on the target context, would suggest processing items starting from index 10 and ending at index 55. To specify the opposite, range could be written as "55..10". This will suggest processing items starting from index 55 and ending at index 10. -defining range explicitly -start_value..end_value -start_value.. (max_value) -(min_value) ..end -start_value (.. end_value = start_value) -defining range implicitly:shorthand for common ranges For scope partials, a shorthand for defining common ranges exists. This is discussed in a dedicated section. Using the shorthand method, ranges are defined by using a special format on the scopetag; either a double-scopetag or an uppercase scopetag. These define EACH NON-EMPTY and EACH AND EVERY ranges respectively. -flags can be used to redefine range Range definitions can be further refined by using symbols known as 'range flags'. These are added directly after a range definition. The two currently available range flags are 'non-empty' -flag and 'invert' -flag. These mostly apply when defining a scope partial range. The non-empty flag is represented with the character '. It refines the range defined by two values by excluding any empty items from the range. This applies to scope partial range definition. So a range defined as "t1..10'" will include all tracks within range starting from track index 1 and ending at track index 10, that are not empty. -invert -visible/non empty -user variables MACROS -overview -defining macros -append any text with @ and macro_definition -using macros -by typing them straight in command line -by using them as part of a script/message -by calling them through a keybind -assigning a macro to a keybind secondary keyboard shortcuts -called through a macro gui GLOBAL FLAGS -overview -flag basic concepts -uppercase: set permanent flag -lowercase: set temporary flag (duration of this message) -options for controlling output -output log -options for controlling gui -close after script 3 MANAGING VADER using invader files handling logs managing scripts IV REFERENCE Script breakdown -script -msg1 -target -content -global flags Numeric values -decimal -hexadecimal Precedence -Nesting -Arithmetic operations Note values -using numeric note values -enterinc literal note values Special symbols -empty -(simple scopetags) -min -max Range flags -empty -inverse -visible / non-empty Defining scope partials -normal scopetag -double scopetag -uppercase scopetag Defining macros