cesaref
commented
5 years ago Glenn,
const is a keyword, along with clamp and wrap - you can't use these names as identifiers. We do however have some of the C++ style 'not quite a keyword', and these are the interpolation types (latch, linear, sinc etc) which are context sensitive, and hence can be used as identifiers. I'll update that part of the document to highlight this.
We have reserved some keywords such as 'import' to cover additions to the language which we feel may be required in the future, or we have plans for. Other examples include exception handling keywords (try, throw, catch) which will allow a natural looking implementation if we add it to the language, and to be honest, i'd be disappointed if someone wants to use these as identifiers as they would cause confusion for newcomers to the language.
sized ints - yes, this is planned, and will follow the float style (so int32 and int64 will be explicitly sized types). We have no unsigned support.
The run() sentence is unclear. There is no concept of consuming inputs, so i'll update this.
You are right, continuous isn't a great choice of word - sequence is clearer.
The further points you make are all good. I'll update the documentation to clarify. Reading an input multiple times returns the same value - the advance() call is used to move time forward. Writing to an output multiple times accumulates rather than overwriting, and advancing without outputting to a stream outputs 0.
sletz
In section "Reserved keywords", "const" is not listed as a keyword, but I couldn't tell if that was an error or if you treat "const" similar to C++ "override" ... a non-keyword identifier that acts as a keyword in certain contexts only.
Similarly for "clamp" and "wrap", are these keywords or not? (They are not currently listed as keywords).
"import" is listed as a keyword, but not mentioned again. If this is intentional, I suggest adding "import is a keyword that is reserved for future use."
I note there is float32, float64, and float which is at least 32 bits, but only int (which is exactly 32 bits) and no explicitly sized versions. This asymmetry is clearly intentional, but it is deserving as an explanation/rationale as it is a rather surprising decision.
"If the run() function returns at any point, this essentially puts it into an inert state where it continues to emit silence on all its inputs and outputs." What does it mean to emit silence on inputs? Does that mean it consumes and discards inputs?
Section "Variables", bullet "State Variables" partially duplicates section "Processor state variables". This redundancy creates potential for divergence in the future. I suggest just placing a forward reference at "Variables" and putting all the normative content at "Processor state variables", or moving section "Processor state variables" into a subsection of "Variables".
"stream - a continuous stream of values" Sorry to be pedantic, but "continuous" has a very specific meaning in math, and it repeats the word "stream", so perhaps "stream - a sequence of values" would be clearer?
Section "Processor oversampling and undersampling" lists examples, but does not specify the syntax. For example, what are the allowed types for the values after "/" and "*", and do they have to be literals?
Section "Built-in intrinsics and constants", I assume these are not keywords, but it might be worth mentioning that explicitly.
In section "Reading and writing to streams", it might be worth mentioning the rationale for using "<<" for outputs but not a similar operator for inputs, as that lack of symmetry is somewhat surprising. Also, should describe what happens if you don't read an input, or read it multiple times (does it consume multiple). Likewise, describe what happens if you don't write to an output, or write to it multiple times.
p.s. see a few more typo fixes at https://github.com/gkasten/SOUL/commit/29b9b9f25052e212dcd2dab9c6ded5bee4aaf0cb Is there a better way that I could offer these, since I know you can't accept pull requests yet?