[whatwg] Definitions of DOMTokenList algorithms andelement.classList

[Ian Hickson]

On Mon, 15 Jun 2009, Kristof Zelechovski wrote:
>
> I would consider it a big advantage to the posterity if the descriptions and
> the algorithms were better formulated and ready to be understood in plain
> text.  For example, regarding 2.8.3 DOMTokenList, (see appendix).  
> 
> LEGEND
> Code samples are in braces; my comments are in brackets, and so are
> important [*changes*], [-deletions-] and [+insertions+]. I understand this
> effect cannot be automatically provided by the HTML view.
> 
> SUMMARY
> Generic changes:
> Find "index"; Replace "position";
> Find "token argument"; Replace "given token"; 
> [this is not strictly necessary, any uniformity would do]
> Insert "the" where appropriate.
> Specific changes: see below.
> 
> Cheers,
> Chris
> 
> Appendix:
> 
> * { tokenCount = tokenList . length }
> --- Returns the number of tokens in the string.
> 
> { [*token*] = tokenList . item([*position*]) }
> { [+token =+] tokenList[[*position*]] }
> --- Returns the token [*at the position given*]. The tokens are sorted
> alphabetically.
> [I would not say that a token has an index; an index is not a property of
> the token.]
> 
> Returns null if [*the position*] is out of range.
> 
> { hasToken = tokenList . has(token) }
> Returns true if the token is present; false otherwise.
> [
> It may be slightly misleading to speak of tokens _in parameters_.  The
> present description means that the corresponding LISP binding would be
> { (let ((has-token (ask token-list 'has 'token)))) }
> Rather than
> { (let ((has-token (ask token-list 'has "token")))) }
> Of course, I may be entirely wrong here in that the first snippet is what is
> intended.
> ]
> 
> Throws an { INVALID_CHARACTER_ERR } exception if [+the+] token contains any
> spaces.  
> [In which case it is not a token at all, so this remark makes no sense.]
> 
> { tokenlist . add(token) }
> [*Inserts*] [+the+] token [+into the list+], unless it is already present.
> [Inserts because the list implementation is sorted.]
> 
> Throws an { INVALID_CHARACTER_ERR } exception if [+the+] token contains any
> spaces. [?]
> 
> { tokenList . remove(token) }
> Removes [+the+] token if it is present.
> 
> Throws an { INVALID_CHARACTER_ERR } exception if [+the+] token contains any
> spaces. [?]
> 
> { hasToken = tokenList . toggle(token) }
> Adds [+the+] token if it is not present, or removes it if it is.
> [Returns what?]
> 
> Throws an { INVALID_CHARACTER_ERR } exception if token contains any spaces.
> [?]
> 
> The { length } attribute must return the number of unique tokens that result
> from splitting the underlying string on spaces. This is the length.  [Why
> this Biblical tone?]
> 
> The [*positions of the supported enumerated tokens within the list*] are the
> numbers in the range [+from+] zero to length[*−*]1, unless the length
> is zero, in which case there are no supported [*enumerated*] properties.
> 
> The { item([*position*]) } method must split the underlying string on
> spaces, sort the resulting list of tokens by Unicode code point, remove
> exact duplicates, and then return the [-indexth-] item in this list [+at the
> given position+]. If [*the position*] is equal to the number of tokens or
> greater, then the method must return null.
> 
> The { has(token) } method must run the following algorithm:
> 
>  1. If the [+given+] token [-argument-] contains any space characters, then
> raise an { INVALID_CHARACTER_ERR } exception and stop the algorithm. 
>  2. Otherwise, split the underlying string on spaces to get the list of
> tokens in the object's underlying string. 
>  3. If the [+given+] token [-indicated by token-] is one of the tokens in
> the object's underlying string then return true and stop this algorithm. 
>  4. Otherwise, return false. 
> 
> The { add(token) } method must run the following algorithm:
> 
>  1. If the [+given+] token [-argument-] contains any space characters, then
> raise an { INVALID_CHARACTER_ERR } exception and stop the algorithm. 
>  2. Otherwise, split the underlying string on spaces to get the list of
> tokens in the object's underlying string. 
>  3. If the given token is already one of the tokens in the { DOMTokenList }
> object's underlying string then stop the algorithm. 
>  4. Otherwise, if the { DOMTokenList } object's underlying string is not the
> empty string and the last character of that string is not a space character,
> then append a U+0020 SPACE character to the end of that string. 
>  5. Append the [*characters*] of [+the+] token to the end of the {
> DOMTokenList } object's underlying string. 
> 
> The { remove(token) } method must run the following algorithm:
> 
>  1. If the [+given+] token [-argument-] contains any space characters, then
> raise an { INVALID_CHARACTER_ERR } exception and stop the algorithm. 
>  2. Otherwise, remove the given token from the underlying string. 
> [ 
> You leave two consecutive spaces here.  
> Why do you insist on not allowing an initial space above? ]
> 
> The { toggle(token)}  method must run the following algorithm:
> 
> [This algorithm is redundant because it is a secondary method that can be
> implemented in terms of {has}, {add} and {remove}. ]
> 
> Objects implementing the DOMTokenList interface must stringify to the
> object's underlying string representation.

I'm afraid I couldn't work out what was being proposed in the e-mail 
above. What is the problem that the above is trying to solve?

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'