diff --git a/docs/changelog.md b/docs/changelog.md index 75025694..2f03aaf0 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -20,6 +20,7 @@ CodeChat Editor. If not, see - [Github master](https://github.com/bjones1/CodeChat_Editor): - Improvements to the build tool. + - Corrections to the C parser. - v0.1.5, 2024-Dec-21 - Improvements to the build tool and tests. - Fixed filewatcher bugs. diff --git a/docs/style_guide.cpp b/docs/style_guide.cpp index 0c303bb9..6b443874 100644 --- a/docs/style_guide.cpp +++ b/docs/style_guide.cpp @@ -135,9 +135,12 @@ double accurate_g( // // Compute the International Gravity Formula (IGF):\ // $IGF = 9.780327 (1 + 0.0053024 \\sin^2 \\phi – 0.0000058 \\sin^2 2\\phi)$ - double IGF = 9.780327 * (1 + 0.0053024 * pow(sin(degrees_latitude), 2) - 0.0000058 * pow(sin(2 * degrees_latitude), 2)); + double IGF = 9.780327 * ( + 1 + 0.0053024 * pow(sin(degrees_latitude), 2) + - 0.0000058 * pow(sin(2 * degrees_latitude), 2) + ); // Compute the Free Air Correction (FAC):\ - // $FAC = -3.086 x 10^{-6} h$ + // $FAC = -3.086 \\cdot 10^{-6} h$ double FAC = -3.086E-6 * height_meters; // $g = IGF + FAC$ return IGF + FAC; @@ -205,11 +208,17 @@ double accurate_g( // CodeChat Editor likewise produces a lot of messy syntax; consider pasting // text only, then reformatting as necessary. // -// ### Highlighting bug +// ### Commenting out code // -// The directions in -// [this issue](https://github.com/bjones1/CodeChat_Editor/issues/27) provide a -// manual edit which enables formatting of highlighted items in a doc block. +// Many developers comment out code while testing, or to save a snippet of code +// for later use. When using the CodeChat Editor, **ensure these comments aren't +// interpreted as a doc block**. Otherwise, this commented out code will be +// interpreted as Markdown then rewritten, which almost certainly corrupts the +// code. To avoid this, append extra characters immediately after the opening +// comment delimiter: for example, use `///` or `/**` in C or C++, `##` in +// Python, etc. See also the example at the end of this file, which includes an +// improved alternative to commenting out code using preprocessor directives for +// C/C++. // // ## Example structure // @@ -250,5 +259,18 @@ class BlinkLed { // ## Code int main(int argc, char* argv[]) { + // Here's an example of commenting code out when using the CodeChat Editor: + /** + * foo(); + */ + // However, when using C/C++, macros provide a nestable way to comment out + // code that may contain block comments (which aren't nestable in + // standardized C/C++): + #if 0 + /* This block comment doesn't end the commented-out code. */ + foo(); + #endif + return 0; -} \ No newline at end of file + +} diff --git a/server/src/lexer/pest/c.pest b/server/src/lexer/pest/c.pest index ded7d55f..578c2f03 100644 --- a/server/src/lexer/pest/c.pest +++ b/server/src/lexer/pest/c.pest @@ -15,6 +15,8 @@ // [http://www.gnu.org/licenses](http://www.gnu.org/licenses). // // # `c.pest` - Pest parser definition for the C language +// +// ## Comments doc_block = _{ inline_comment | block_comment } // Per the @@ -29,21 +31,14 @@ white_space = { (" " | "\t" | vertical_tab | form_feed)* } // [C standard, section 6.4.9](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=65), // defines inline and block comments. // -// ## Inline comments +// ### Inline comments inline_comment_delims = _{ inline_comment_delim_0 } inline_comment_delim_0 = { "//" } inline_comment_delim_1 = { unused } inline_comment_delim_2 = { unused } -// Per the -// [C standard, section 5.1.1.2](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=24), -// if a line of code ends with a backslash, it continues on the next line. This -// is a logical line; treat it as a single line. Therefore, consider a -// backslash-newline (or anything that's not a newline) a part of the current -// logical line. -logical_line_char = _{ ("\\" ~ NEWLINE) | not_newline } -inline_comment_char = _{ logical_line_char } +inline_comment_char = _{ not_newline } -// ## Block comments +// ### Block comments block_comment = { block_comment_0 } block_comment_opening_delim_0 = { "/*" } block_comment_opening_delim_1 = { unused } @@ -52,7 +47,34 @@ block_comment_closing_delim_0 = { "*/" } block_comment_closing_delim_1 = { unused } block_comment_closing_delim_2 = { unused } -// ## Code blocks +// ## Code +// +// Per the +// [C standard, section 5.1.1.2](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#page=24), +// if a line of code ends with a backslash, it continues on the next line. This +// is a logical line; treat it as a single line. Therefore, consider a +// backslash-newline (or anything that's not a newline) a part of the current +// logical line. Note that this parser doesn't apply this rule to comments +// (which, per the spec, it should) for several reasons: +// +// 1. Comments continued onto another line don't look like a comment; this +// would confuse most developers. +// 2. The backslash-newline in a comment creates a +// [hard line break](https://spec.commonmark.org/0.31.2/#hard-line-breaks) +// in Markdown, which means inserting a hard line break this way in an +// inline comment requires the next line to omit the inline comment +// delimiters. For example:  +// +// ```C +// // This is a hard line break\ +// followed by a comment which must not include the // inline comment +// // delimiter on the line after the line break, but which must +// include them on following lines. +// ``` +// 3. The CodeChat Editor web-to-code function produces incorrect results in +// this case, adding a comment delimiter when it shouldn't. To fix this, it +// would have to look for a backslash newline only in C/C++-like languages. +logical_line_char = _{ ("\\" ~ NEWLINE) | not_newline } code_line_token = _{ logical_line_char } // ## Dedenter