TAP escape syntax

From Test Anything Protocol

Jump to: navigation, search

Contents

[edit] Problem

TAP currently defines no way to escape characters. This is particularly important for test names: 

   ok 1 - this # is part of the description not a directive

[edit] Solution 1: Backslash

Test::Builder uses a \. 

   ok 1 - this \# is part of the description not a directive

Test::Harness currently honors this but its not part of the spec.

[edit] 1b: backslash escalation

Does this mean \ should also be escaped as \\ so that 

  ok 1 - this description ends with a \\# todo

or is the directive separator " # " rather than plain "#"?

[edit] Solution 2: # is not a comment here

If the "# todo" and "# skip" suffixes to the test name are the only directives that make '#' look special, maybe no escaping is required?

"TAP consumers should not treat # in a special way unless followed by a known directive" is the smallest change to the spec to remove undefined-ness.

Advantages
  • TAP producers do not need to change.
  • There are fewer TAP consumers to maintain. (And maybe they don't need to change either.)
Disadvantages
  • Some test names cannot be encoded under this scheme. 
  not ok 1 - cannot search for " # todo" in canned TAP files # skip head hurts now

[edit] Solution 3: different escape notation

The disadvantage of solution 1 "\#" is that both sides need the upgrade,

  • if the producer doesn't \# then the new feature is available but unused.
  • if the consumer doesn't treat \# right then the new feature is unavailable and the description has an extra character before the unwante directive.
Either way, consumers continue to do... whatever bad thing they do in TAP12. (Fail due to invalid directive? That is not so bad, but still undefined behaviour.)

If the aim is to get an arbitrary string into the description, any of

  • %23 and %25 (CGI / URL encoding)
  • \x23 and \x25
  • \043 and \045

have the useful properties

  • avoid using the # character (Consumers that don't know don't see it.)
  • simple way to encode the symbol stolen to give new meaning
  • most programmers will understand it when they see it
  • if you want newlines in your description, now you can have them. Hmmm. Did we allow nul bytes already?

Changing the interpretation of new-producer descriptions under old-consumer is inevitable with these schemes, but should(tm) be harmless.

[edit] Solution 4: double to ##

Included for completeness / because SQL does it. 

  ok 1 - Bobby ##TAP## Comments was here

[edit] Status

The "solution 1: backslash" proposal is scheduled for inclusion in a future version of TAP.

[edit] For "solution 1: backslash"

(the above signed when there was only solution 1 on the page, before I added section 1b)

[edit] For "further discussion"

  • Mcast 00:59, 17 May 2011 (BST)

[edit] Against

Retrieved from "http://www.testanything.org/wiki/index.php/TAP_escape_syntax"
Personal tools