commit 9d237bb00a32f39a6acd1351f81e905f42247699 Author: Nick Mathewson <nickm@torproject.org> Date: Tue Jul 21 14:40:22 2015 -0400 Actually, write the torrc format in ABNF This should make it more clear what I meant, if you know how to read ABNF. (Thanks to rl1987 for correcting numerous issues here) --- doc/torrc_format.txt | 88 ++++++++++++++++++++++++-------------------------- 1 file changed, 43 insertions(+), 45 deletions(-) diff --git a/doc/torrc_format.txt b/doc/torrc_format.txt index 3ca187f..7a80990 100644 --- a/doc/torrc_format.txt +++ b/doc/torrc_format.txt @@ -14,68 +14,66 @@ does, not what it should do. 1. File Syntax - # A file is interpreted as every Entry in the file, in order. - TorrcFile = Line* + ; The syntax here is defined an Augmented Backus-Naur form, as + ; specified in RFC5234. - Line = BlankLine | Entry + ; A file is interpreted as every Entry in the file, in order. + TorrcFile = *Line - BlankLine = WS* OptComment LF - | WS* LF + Line = BlankLine / Entry - OptComment = - | Comment + BlankLine = *WSP OptComment LF + BlankLine =/ *WSP LF - Comment = '#' NonLF* + OptComment = [ Comment ] - # Each Entry is interpreted as an optional "Magic" flag, a key, and a - # value. - Entry = SP* OptMagic Key (SP+ | '\\' NL SP*)+ Val LF - | SP* OptMagic Key (SP* | '\\' NL SP*)* LF + Comment = "#" *NonLF - OptMagic = - | "+" - | "/" + ; Each Entry is interpreted as an optional "Magic" flag, a key, and a + ; value. + Entry = *WSP [ Magic ] Key 1*(1*WSP / "\" NL *WSP) Val LF + Entry =/ *WSP [ Magic ] Key *( *WSP / "\" NL *WSP) LF - # Keys are always specified verbatim. They are case insensitive. It - # is an error to specify a key that Tor does not recognize. - Key = KC* + Magic = "+" / "/" - # Sadly, every kind of value is decoded differently... - Val = QuotedVal | ContinuedVal | PlainVal + ; Keys are always specified verbatim. They are case insensitive. It + ; is an error to specify a key that Tor does not recognize. + Key = 1*KC - # The text of a PlainVal is the text of its PVBody portion, - # plus the optional trailing backslash. - PlainVal = PVBody* ('\\')? SP* OptComment + ; Sadly, every kind of value is decoded differently... + Val = QuotedVal / ContinuedVal / PlainVal - # Note that a PVBody is copied verbatim. Slashes are included - # verbatim. No changes are made. Note that a body may be empty. - PVBody = (VC | '\\' NonLF ) * + ; The text of a PlainVal is the text of its PVBody portion, + ; plus the optional trailing backslash. + PlainVal = PVBody [ "\" ] *WSP OptComment - # The text of a ContinuedVal is the text of each of its PVBody - # sub-elements, in order, concatenated. - ContinuedVal = CVal1 CVal2* CVal3 + ; Note that a PVBody is copied verbatim. Slashes are included + ; verbatim. No changes are made. Note that a body may be empty. + PVBody = * (VC / "\" NonLF ) - CVal1 = PVBody '\\' LF - CVal2 = PVBody ( '\\' LF | Comment LF ) + ; The text of a ContinuedVal is the text of each of its PVBody + ; sub-elements, in order, concatenated. + ContinuedVal = CVal1 *CVal2 CVal3 + + CVal1 = PVBody "\" LF + CVal2 = PVBody ( "\" LF / Comment LF ) CVal3 = PVBody - # The text of a QuotedVal is decoded as if it were a C string. - QuotedVal = DQ QVBody DQ SP* Comment + ; The text of a QuotedVal is decoded as if it were a C string. + QuotedVal = DQ QVBody DQ *WSP Comment + + QVBody = QC + QVBody =/ "\" ( "n" / "r" / "t" / "\" / "'" / DQUOTE ) + QVBOdy =/ "\" ( "x" 2HEXDIG / 1*3OCTDIG ) - QVBody = QC - | '\\' ( 'n' | 'r' | 't' | '\\' | '\'' | DQ | 'x' XD XD | OD OD? OD? ) + ; Anything besides NUL and LF + NonLF = %x01-%x09 / %x0b - %xff - XD = any hexadecimal digit - OD = any octal digit + OCTDIG = '0' - '7' - NonLF = Any character but '\n' - LF = '\n' | EOF - WS = ' ' | '\t' | '\r' - SP = ' ' | '\t' - DQ = '\"' - KC = Any character except an isspace() character or '#' - VC = Any character except '\\', '\n', or '#' - QC = Any character except '\n', '\\', or '\"' + KC = Any character except an isspace() character or '#' or NUL + VC = Any character except '\\', '\n', '#', or NUL + QC = Any character except '\n', '\\', '\"', or NUL 2. Mid-level Semantics