Jamoma API  0.6.0.a19
TTScript.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup modularLibrary
4  *
5  * @brief A Script Object
6  *
7  * @details TODO: Add more info
8  *
9  * @authors Théo de la Hogue
10  *
11  * @copyright © 2010, Théo de la Hogue @n
12  * This code is licensed under the terms of the "New BSD License" @n
13  * http://creativecommons.org/licenses/BSD/
14  */
15 
16 
17 #ifndef __TT_SCRIPT_H__
18 #define __TT_SCRIPT_H__
19 
20 #include "TTModularIncludes.h"
21 #include <thread>
22 
23 /** About line schemas :
24 
25  kTTSym_command :
26  address : a TTNodeAddress
27  value : the value to send
28  unit : the unit to use
29  ramp : a ramp time
30 
31  kTTSym_comment :
32  value : the comment
33 
34  kTTSym_flag :
35  name : the name of the flag
36  value : a TTvalue containing any extra info relative to this flag
37 
38  */
39 
40 class TTMODULAR_EXPORT TTScript : public TTObjectBase
41 {
43 
44 private:
45 
46  TTBoolean mFlattened; ///< ATTRIBUTE : is the script ready for quick operation process or not ?
47  // TODO JamomaCore #305 : TTList : allow to register as none pointer members
48  TTListPtr mLines; ///< a linked list containing all lines of the script
49  // TODO JamomaCore #305 : TTList : allow to register as none pointer members
50  TTListPtr mFlattenedLines; ///< a linked list containing all lines of the script and the subscripts flattened for quick access
51 
52  TTObject mSubScript; ///< the current sub script to manage
53  TTObject mParentScript; ///< the current parent script to manage (usefull for ReadFrom method)
54 
55  TTObject mReturnLineCallback; ///< a callback to return back lines to the owner of this script
56 
57 
58  // get the lines list
59  TTErr getLines(TTValue& value);
60  TTErr getFlattenedLines(TTValue& value);
61 
62  /** Clear all lines of the script */
63  TTErr Clear();
64 
65  /** Process all command lines of the script and the subscripts to cache all lines into a Flattened quick access link list
66  Each line binds also to the node in the directory in order to increase the recall, interpolation, mix.
67  However this is dangerous because if the node dispeared, their will be a BAD_ACCESS.
68  This is usefull to increase the speed of any operation */
69  TTErr Flatten(const TTValue& inputValue, TTValue& outputValue);
70  TTErr Unflatten();
71 
72  /** Run all command lines of the script (or the Flattened lines if ready) */
73  TTErr Run(const TTValue& inputValue, TTValue& outputValue);
74  TTErr RunFlattened();
75 
76  /** Run one command of the script */
77  TTErr RunCommand(const TTValue& inputValue, TTValue& outputValue);
78 
79  /** Remove one command of the script */
80  TTErr RemoveCommand(const TTValue& inputValue, TTValue& outputValue);
81 
82  /** Dump all lines of the script using mReturnLineCallback (or the Flattened lines if ready) */
83  TTErr Dump(const TTValue& inputValue, TTValue& outputValue);
84  TTErr DumpFlattened();
85 
86  /** Dump one line of the script using mReturnLineCallback */
87  TTErr DumpLine(const TTValue& inputValue, TTValue& outputValue);
88 
89  /** Append any line to the script (a parsing will find which kind of line it is) */
90  TTErr Append(const TTValue& newLine, TTValue& outputValue);
91 
92  /** Append a command line to the script and output the dictionnary associated to the parsed line
93  <address, value, unit, ramp, ...> */
94  TTErr AppendCommand(const TTValue& newCommand, TTValue& outputValue);
95 
96  /** Append a comment line to the script and output the dictionnary associated to the parsed line
97  <comment> */
98  TTErr AppendComment(const TTValue& newComment, TTValue& outputValue);
99 
100  /** Append a flag line to the script and output the dictionnary associated to the parsed line
101  <name, arg1, arg2, ...> */
102  TTErr AppendFlag(const TTValue& newflagAndArguments, TTValue& outputValue);
103 
104  /** Append a sub script */
105  TTErr AppendScript(const TTValue& newScript, TTValue& outputValue);
106 
107  /** needed to be handled by a TTXmlHandler */
108  TTErr WriteAsXml(const TTValue& inputValue, TTValue& outputValue);
109  TTErr ReadFromXml(const TTValue& inputValue, TTValue& outputValue);
110 
111  /** needed to be handled by a TTTextHandler */
112  TTErr WriteAsText(const TTValue& inputValue, TTValue& outputValue);
113  TTErr ReadFromText(const TTValue& inputValue, TTValue& outputValue);
114 
115  friend TTErr TTMODULAR_EXPORT TTScriptInterpolate(TTObject script1, TTObject script2, TTFloat64 position);
116  friend TTErr TTMODULAR_EXPORT TTScriptMix(const TTValue& scripts, const TTValue& factors);
117  friend TTErr TTMODULAR_EXPORT TTScriptMerge(TTObject scriptToMerge, TTObject mergedScript);
118  friend TTErr TTMODULAR_EXPORT TTScriptOptimize(TTObject aScriptToOptimize, TTObject aScript, TTObject optimizedScript);
119  friend TTErr TTMODULAR_EXPORT TTScriptCopy(TTObject scriptTocopy, TTObject aScriptCopy);
120 };
121 
122 typedef TTScript* TTScriptPtr;
123 
124 
125 /* Parse a value into a comment, a flag or a command line.
126  Returns NULL in case of error */
127 TTDictionaryBasePtr TTMODULAR_EXPORT TTScriptParseLine(const TTValue& newLine);
128 
129 /* Parse a value into a comment line
130  Returns NULL in case of error */
131 TTDictionaryBasePtr TTMODULAR_EXPORT TTScriptParseComment(const TTValue& newComment);
132 
133 /* Parse a value into a WAIT line
134  Returns NULL in case */
135 TTDictionaryBasePtr TTScriptParseWait(const TTValue& duration);
136 
137 /* Parse a value into a flag line
138  Returns NULL in case of error */
139 TTDictionaryBasePtr TTMODULAR_EXPORT TTScriptParseFlag(const TTValue& newflagAndArguments);
140 
141 /* Parse a value into a command line.
142  Returns NULL in case of error */
143 TTDictionaryBasePtr TTMODULAR_EXPORT TTScriptParseCommand(const TTValue& newCommand);
144 
145 /* Parse a value into a sub script line and optionnaly pass a callback to output
146  Returns NULL in case of error */
147 TTDictionaryBasePtr TTMODULAR_EXPORT TTScriptParseScript(const TTValue& newScript);
148 
149 /* Interpolate between two scripts
150  note : we assume that the Bind method have been called before on the two scripts */
151 TTErr TTMODULAR_EXPORT TTScriptInterpolate(TTObject script1, TTObject script2, TTFloat64 position);
152 
153 /* Mix several scripts together
154  note : we assume that the Bind method have been called before on each scripts */
155 TTErr TTMODULAR_EXPORT TTScriptMix(const TTValue& scripts, const TTValue& factors);
156 TTFloat64 TTMODULAR_EXPORT TTScriptMixLine(TTDictionaryBasePtr lineToMix, TTSymbol dataType, TTUInt32 mixSize, TTFloat64 factor, TTValue& mixedValue, TTBoolean init=NO);
157 
158 /* Merge a script into another without redundant command lines */
159 TTErr TTMODULAR_EXPORT TTScriptMerge(TTObject scriptToMerge, TTObject mergedScript);
160 
161 /* Optimize a script comparing to another to remove redundant command lines */
162 TTErr TTMODULAR_EXPORT TTScriptOptimize(TTObject aScriptToOptimize, TTObject aScript, TTObject optimizedScript);
163 
164 /* Copy a script */
165 TTErr TTMODULAR_EXPORT TTScriptCopy(TTObject scriptTocopy, TTObject aScriptCopy);
166 
167 /* a TTFunctionMatch to find a line in the script depending on the address */
168 void TTMODULAR_EXPORT TTScriptFindAddress(const TTValue& lineValue, TTPtr addressPtrToMatch, TTBoolean& found);
169 
170 /* a TTFunctionMatch to find a line in the script depending on the target address (in mFlattenedLines only) */
171 void TTMODULAR_EXPORT TTScriptFindTarget(const TTValue& lineValue, TTPtr addressPtrToMatch, TTBoolean& found);
172 
173 /* Copy a line */
174 TTDictionaryBasePtr TTMODULAR_EXPORT TTScriptCopyLine(TTDictionaryBasePtr lineTocopy);
175 
176 #endif // __TT_SCRIPT_H__
bool TTBoolean
Boolean flag, same as Boolean on the Mac.
Definition: TTBase.h:167
TTModular Library.
A type that contains a key and a value.
Create and use Jamoma object instances.
Definition: TTObject.h:29
About line schemas :
Definition: TTScript.h:40
Base class for all first-class Jamoma objects.
Definition: TTObjectBase.h:109
double TTFloat64
64 bit floating point number
Definition: TTBase.h:188
#define TTCLASS_SETUP(className)
TODO Doxygen: need more comments here.
Definition: TTFoundation.h:54
void * TTPtr
A generic pointer.
Definition: TTBase.h:248
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
std::uint32_t TTUInt32
32 bit unsigned integer
Definition: TTBase.h:178
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34