KiCad PCB EDA Suite
Loading...
Searching...
No Matches
drc_rules_downgrade.h
Go to the documentation of this file.
1/*
2 * This program source code file is part of KiCad, a free EDA CAD application.
3 *
4 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
5 *
6 * This program is free software: you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation, either version 3 of the License, or (at your
9 * option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <https://www.gnu.org/licenses/>.
18 */
19
20#ifndef DRC_RULES_DOWNGRADE_H
21#define DRC_RULES_DOWNGRADE_H
22
23#include <algorithm>
24#include <cctype>
25#include <string>
26#include <vector>
27
28#include <wx/intl.h>
29
30#include <dsnlexer.h>
31#include <ki_exception.h>
32#include <downgrade_target.h>
34
35// The old rules parsers are all-or-nothing. One unknown keyword anywhere makes the target drop
36// every custom rule and refuse to run DRC. So the export filters the file: rules the target
37// cannot parse are commented out and reported, surviving rules are kept byte-identical apart
38// from constraint kinds the target reads by an older name.
39
43{
44 for( const DRC_RULE_VOCABULARY& vocabulary : DRC_RULE_VOCABULARIES )
45 {
46 if( aTarget.m_id == vocabulary.m_targetId )
47 return &vocabulary;
48 }
49
50 return nullptr;
51}
52
53
55inline constexpr const char* DRC_RULE_SEMANTIC_BREAKS[] = {
56 // Releases before 10.0.7 test a zone item's fill rather than its outline.
57 "intersectsarea",
58};
59
60
62inline bool DrcVocabularyHas( const char* const* aWords, size_t aCount, const std::string& aWord )
63{
64 return std::binary_search( aWords, aWords + aCount, aWord );
65}
66
67
70{
71 const char* m_current;
72 const char* m_legacy;
73};
74
75
77 // Releases before 11.0 check only text with it, graphic shapes go unchecked
78 { "line_width", "text_thickness" },
79};
80
81
83inline std::string DrcConstraintKindForTarget( const std::string& aKind, const DRC_RULE_VOCABULARY& aVocabulary )
84{
85 if( DrcVocabularyHas( aVocabulary.m_tokens, aVocabulary.m_tokenCount, aKind ) )
86 return aKind;
87
89 {
90 if( aKind == rename.m_current )
91 return rename.m_legacy;
92 }
93
94 return aKind;
95}
96
97
99{
100 wxString m_text;
101 std::vector<wxString> m_dropped;
102 wxString m_error;
103};
104
105
107{
108 int m_type;
109 std::string m_text;
110 size_t m_offset;
111};
112
113
116{
117 size_t m_start = 0;
118 size_t m_end = 0;
119 size_t m_first = 0;
120 size_t m_last = 0;
121 std::string m_head;
122 wxString m_name;
123};
124
125
128inline bool TokenizeDrcRules( const std::string& aText, std::vector<DRC_RULE_TOKEN>& aTokens, wxString& aError )
129{
130 std::vector<size_t> lineStarts{ 0 };
131
132 for( size_t i = 0; i < aText.size(); i++ )
133 {
134 if( aText[i] == '\n' )
135 lineStarts.push_back( i + 1 );
136 }
137
138 DSNLEXER lexer( aText, wxT( "drc_rules_downgrade" ) );
139 lexer.SetCommentsAreTokens( true );
140
141 try
142 {
143 for( int type = lexer.NextTok(); type != DSN_EOF; type = lexer.NextTok() )
144 {
145 size_t offset = lineStarts[lexer.CurLineNumber() - 1] + lexer.CurOffset() - 1;
146
147 // The lexer places a string at its first character, after the opening quote.
148 if( type == DSN_STRING )
149 offset--;
150
151 aTokens.push_back( { type, lexer.CurText(), offset } );
152 }
153 }
154 catch( const IO_ERROR& error )
155 {
156 aError = error.Problem();
157 return false;
158 }
159
160 return true;
161}
162
163
166inline bool SplitDrcRuleBlocks( const std::vector<DRC_RULE_TOKEN>& aTokens, std::vector<DRC_RULE_BLOCK>& aBlocks,
167 wxString& aError )
168{
169 int depth = 0;
170
171 for( size_t i = 0; i < aTokens.size(); i++ )
172 {
173 const DRC_RULE_TOKEN& token = aTokens[i];
174
175 if( token.m_type == DSN_SYMBOL && token.m_text[0] == '#' )
176 {
177 aError = _( "Design rule comments must start on a separate line." );
178 return false;
179 }
180
181 if( token.m_type == DSN_COMMENT )
182 continue;
183
184 if( depth == 0 )
185 {
186 if( token.m_type != DSN_LEFT )
187 {
188 aError = _( "Design rules contain text outside a rule." );
189 return false;
190 }
191
192 DRC_RULE_BLOCK block;
193 block.m_start = token.m_offset;
194 block.m_first = i;
195
196 auto nextCode = [&aTokens]( size_t aFrom )
197 {
198 while( aFrom < aTokens.size() && aTokens[aFrom].m_type == DSN_COMMENT )
199 aFrom++;
200
201 return aFrom;
202 };
203
204 size_t head = nextCode( i + 1 );
205
206 if( head < aTokens.size() && aTokens[head].m_type == DSN_SYMBOL )
207 block.m_head = aTokens[head].m_text;
208
209 size_t name = nextCode( head + 1 );
210
211 if( block.m_head == "rule" && name < aTokens.size() && aTokens[name].m_type != DSN_LEFT
212 && aTokens[name].m_type != DSN_RIGHT )
213 {
214 block.m_name = wxString::FromUTF8( aTokens[name].m_text.c_str() );
215 }
216
217 aBlocks.push_back( block );
218 }
219
220 if( token.m_type == DSN_LEFT )
221 {
222 depth++;
223 }
224 else if( token.m_type == DSN_RIGHT )
225 {
226 depth--;
227
228 if( depth == 0 )
229 {
230 aBlocks.back().m_end = token.m_offset + 1;
231 aBlocks.back().m_last = i;
232 }
233 }
234 }
235
236 if( depth != 0 )
237 {
238 aError = _( "Unbalanced parentheses in design rules." );
239 return false;
240 }
241
242 return true;
243}
244
245
248inline bool DrcRuleUnsupportedByTarget( const std::vector<DRC_RULE_TOKEN>& aTokens, const DRC_RULE_BLOCK& aBlock,
249 const DRC_RULE_VOCABULARY& aVocabulary,
250 std::vector<size_t>* aRenamed = nullptr )
251{
252 std::vector<std::string> nodes;
253 std::vector<std::string> words;
254 std::string expressions;
255 std::string values;
256 bool headPending = false;
257 bool kindPending = false;
258 bool namePending = false;
259
260 // String literals inside an expression are not names, so only their quotes are kept as gaps.
261 auto addExpression = [&expressions]( const std::string& aExpression )
262 {
263 char quote = 0;
264
265 for( size_t j = 0; j < aExpression.size(); j++ )
266 {
267 char c = aExpression[j];
268
269 if( quote )
270 {
271 if( c == '\\' && j + 1 < aExpression.size() )
272 j++;
273 else if( c == quote )
274 quote = 0;
275 }
276 else if( c == '\'' || c == '"' )
277 {
278 quote = c;
279 expressions += ' ';
280 }
281 else
282 {
283 expressions += c;
284 }
285 }
286
287 expressions += '\n';
288 };
289
290 for( size_t i = aBlock.m_first; i <= aBlock.m_last; i++ )
291 {
292 const DRC_RULE_TOKEN& token = aTokens[i];
293
294 if( token.m_type == DSN_COMMENT )
295 continue;
296
297 if( token.m_type == DSN_LEFT )
298 {
299 nodes.emplace_back();
300 headPending = true;
301 continue;
302 }
303
304 if( token.m_type == DSN_RIGHT )
305 {
306 // A node with no head is not grammar for any reader.
307 if( headPending )
308 return true;
309
310 nodes.pop_back();
311 continue;
312 }
313
314 if( token.m_text.find( "${" ) != std::string::npos )
315 {
316 // A text variable is syntax, and a target without it fails to read the rule at all.
317 if( !aVocabulary.m_textVariables )
318 return true;
319
320 std::string folded = token.m_text;
321
322 for( char& c : folded )
323 c = static_cast<char>( std::tolower( static_cast<unsigned char>( c ) ) );
324
325 // Releases before 10.0.6 read a component class selector as a reference designator.
326 if( folded.find( "${class:" ) != std::string::npos )
327 return true;
328 }
329
330 if( headPending )
331 {
332 headPending = false;
333
334 if( token.m_type != DSN_SYMBOL )
335 return true;
336
337 nodes.back() = token.m_text;
338 words.push_back( token.m_text );
339 kindPending = token.m_text == "constraint";
340 namePending = token.m_text == "rule";
341 continue;
342 }
343
344 const std::string& node = nodes.back();
345
346 if( namePending )
347 {
348 namePending = false;
349 }
350 else if( kindPending )
351 {
352 // The constraint kind is grammar, and three kinds change how what follows is read.
353 kindPending = false;
354
355 std::string kind = DrcConstraintKindForTarget( token.m_text, aVocabulary );
356
357 if( aRenamed && kind != token.m_text )
358 aRenamed->push_back( i );
359
360 words.push_back( kind );
361
362 if( token.m_text == "assertion" || token.m_text == "disallow" || token.m_text == "zone_connection" )
363 nodes.back() = token.m_text;
364 }
365 else if( node == "condition" || node == "assertion" )
366 {
367 addExpression( token.m_text );
368 }
369 else if( node == "min" || node == "max" || node == "opt" )
370 {
371 values += token.m_text + ' ';
372 }
373 else if( node == "layer" )
374 {
375 // A layer node names a board layer, which is not grammar.
376 }
377 else if( node == "disallow" || node == "zone_connection" )
378 {
379 // The readers accept these items quoted, so they are keywords in disguise.
380 words.push_back( token.m_text );
381 }
382 else if( token.m_type != DSN_STRING && token.m_type != DSN_NUMBER )
383 {
384 words.push_back( token.m_text );
385 }
386 }
387
388 for( const std::string& word : words )
389 {
390 // A dotted name is a layer or similar, never grammar.
391 if( word.find( '.' ) != std::string::npos )
392 continue;
393
394 if( !DrcVocabularyHas( aVocabulary.m_tokens, aVocabulary.m_tokenCount, word ) )
395 return true;
396 }
397
398 auto isWord = []( char c )
399 {
400 return std::isalnum( static_cast<unsigned char>( c ) ) || c == '_';
401 };
402
403 std::string folded = expressions;
404
405 for( char& c : folded )
406 c = static_cast<char>( std::tolower( static_cast<unsigned char>( c ) ) );
407
408 // Inside an expression a word followed by a parenthesis is a function call, and a word after
409 // a dot is a property. Both must exist in the target.
410 for( size_t i = 0; i < folded.size(); i++ )
411 {
412 if( !std::isalpha( static_cast<unsigned char>( folded[i] ) ) && folded[i] != '_' )
413 continue;
414
415 if( i > 0 && isWord( folded[i - 1] ) )
416 continue;
417
418 size_t end = i;
419
420 while( end < folded.size() && isWord( folded[end] ) )
421 end++;
422
423 const std::string word = folded.substr( i, end - i );
424
425 size_t next = end;
426
427 while( next < folded.size() && std::isspace( static_cast<unsigned char>( folded[next] ) ) )
428 next++;
429
430 size_t prev = i;
431
432 while( prev > 0 && std::isspace( static_cast<unsigned char>( folded[prev - 1] ) ) )
433 prev--;
434
435 if( next < folded.size() && folded[next] == '(' )
436 {
437 for( const char* broken : DRC_RULE_SEMANTIC_BREAKS )
438 {
439 if( word == broken )
440 return true;
441 }
442
443 if( !DrcVocabularyHas( aVocabulary.m_functions, aVocabulary.m_functionCount, word ) )
444 return true;
445 }
446 else if( prev > 0 && folded[prev - 1] == '.' )
447 {
448 // Parent navigation is new, but the old standalone Parent string property is supported.
449 if( word == "parent" && next < folded.size() && folded[next] == '.' )
450 return true;
451
452 if( !DrcVocabularyHas( aVocabulary.m_properties, aVocabulary.m_propertyCount, word ) )
453 return true;
454 }
455
456 i = end;
457 }
458
459 // A unit is the letters after a number, glued to it or not. It must be one the target's
460 // value resolver knows.
461 const std::string numeric = values + '\n' + expressions;
462
463 for( size_t i = 0; i < numeric.size(); i++ )
464 {
465 if( !std::isalpha( static_cast<unsigned char>( numeric[i] ) ) )
466 continue;
467
468 if( i > 0 && ( std::isalpha( static_cast<unsigned char>( numeric[i - 1] ) ) || numeric[i - 1] == '_' ) )
469 continue;
470
471 size_t before = i;
472
473 while( before > 0 && std::isspace( static_cast<unsigned char>( numeric[before - 1] ) ) )
474 before--;
475
476 size_t end = i;
477
478 while( end < numeric.size() && isWord( numeric[end] ) )
479 end++;
480
481 if( before > 0 && std::isdigit( static_cast<unsigned char>( numeric[before - 1] ) )
482 && !DrcVocabularyHas( aVocabulary.m_units, aVocabulary.m_unitCount, numeric.substr( i, end - i ) ) )
483 {
484 return true;
485 }
486
487 i = end;
488 }
489
490 return false;
491}
492
493
495inline std::string CommentOutDrcBlock( const std::string& aBlock )
496{
497 std::string out = "# ";
498
499 for( char c : aBlock )
500 {
501 out += c;
502
503 if( c == '\n' )
504 out += "# ";
505 }
506
507 return out;
508}
509
510
514inline DRC_RULES_FILTER_RESULT FilterDrcRulesForTarget( const wxString& aRulesText, const DOWNGRADE_TARGET& aTarget )
515{
516 std::string text = aRulesText.ToStdString( wxConvUTF8 );
517
519
520 const DRC_RULE_VOCABULARY* vocabulary = FindDrcRuleVocabulary( aTarget );
521
522 if( !vocabulary )
523 {
524 result.m_error = wxString::Format( _( "No design rule vocabulary is recorded for %s." ), aTarget.m_name );
525 return result;
526 }
527
528 std::vector<DRC_RULE_TOKEN> tokens;
529 std::vector<DRC_RULE_BLOCK> blocks;
530
531 if( !TokenizeDrcRules( text, tokens, result.m_error ) || !SplitDrcRuleBlocks( tokens, blocks, result.m_error ) )
532 return result;
533
534 const wxString header = wxT( "(version 1)" );
535 const wxString eol = text.find( "\r\n" ) != std::string::npos ? wxT( "\r\n" ) : wxT( "\n" );
536
537 size_t consumed = 0;
538 bool headerWritten = false;
539 bool commentedOut = false;
540
541 auto endsOnBlankLine = []( const wxString& aText )
542 {
543 int lineStart = aText.Find( '\n', true );
544 return aText.Mid( lineStart == wxNOT_FOUND ? 0 : lineStart + 1 ).Trim().IsEmpty();
545 };
546
547 for( const DRC_RULE_BLOCK& block : blocks )
548 {
549 // A comment travels with the block after it, so a dropped rule takes its comment along.
550 wxString prefix = wxString::FromUTF8( text.substr( consumed, block.m_start - consumed ).c_str() );
551 std::string body = text.substr( block.m_start, block.m_end - block.m_start );
552 consumed = block.m_end;
553
554 // The version header is rewritten in place, so a comment above it stays above it.
555 if( block.m_head == "version" )
556 {
557 result.m_text += prefix;
558
559 if( !headerWritten )
560 result.m_text += header;
561
562 headerWritten = true;
563 continue;
564 }
565
566 if( !headerWritten )
567 {
568 result.m_text += header + eol;
569 headerWritten = true;
570 }
571
572 std::vector<size_t> renamed;
573 bool unsupported = block.m_head != "rule" || DrcRuleUnsupportedByTarget( tokens, block, *vocabulary, &renamed );
574
575 if( !unsupported )
576 {
577 // Back to front, so earlier offsets stay valid
578 for( auto it = renamed.rbegin(); it != renamed.rend(); ++it )
579 {
580 const DRC_RULE_TOKEN& token = tokens[*it];
581 size_t at = body.find( token.m_text, token.m_offset - block.m_start );
582
583 body.replace( at, token.m_text.size(), DrcConstraintKindForTarget( token.m_text, *vocabulary ) );
584 }
585 }
586
587 result.m_text += prefix;
588
589 // A comment runs to the end of its line, so a commented block and whatever follows it
590 // each start on a line of their own.
591 if( ( unsupported || commentedOut ) && !endsOnBlankLine( result.m_text ) )
592 result.m_text += eol;
593
594 if( unsupported )
595 {
596 result.m_dropped.push_back( block.m_name );
597 result.m_text += wxT( "# Not supported by " ) + aTarget.m_name + wxT( ":" ) + eol;
598 result.m_text += wxString::FromUTF8( CommentOutDrcBlock( body ).c_str() );
599 }
600 else
601 {
602 result.m_text += wxString::FromUTF8( body.c_str() );
603 }
604
605 commentedOut = unsupported;
606 }
607
608 if( !headerWritten )
609 result.m_text += header + eol;
610
611 // Comments after the last block, which by now include every commented rule that was last.
612 result.m_text += wxString::FromUTF8( text.substr( consumed ).c_str() );
613
614 if( !result.m_text.EndsWith( wxT( "\n" ) ) )
615 result.m_text += eol;
616
617 return result;
618}
619
620#endif // DRC_RULES_DOWNGRADE_H
const char * name
Implement a lexical analyzer for the SPECCTRA DSN file format.
Definition dsnlexer.h:75
const char * CurText() const
Return a pointer to the current token's text.
Definition dsnlexer.h:415
int NextTok()
Return the next token found in the input file or DSN_EOF when reaching the end of file.
Definition dsnlexer.cpp:545
bool SetCommentsAreTokens(bool val)
Change the handling of comments.
Definition dsnlexer.h:304
int CurOffset() const
Return the byte offset within the current line, using a 1 based index.
Definition dsnlexer.h:473
int CurLineNumber() const
Return the current line number within my LINE_READER.
Definition dsnlexer.h:445
Hold an error message and may be used when throwing exceptions containing meaningful error messages.
virtual const wxString Problem() const
what was the problem?
std::string CommentOutDrcBlock(const std::string &aBlock)
Prefix every line, so the target reads the whole block as comments.
bool DrcVocabularyHas(const char *const *aWords, size_t aCount, const std::string &aWord)
The generated arrays are sorted, so membership is a binary search.
constexpr const char * DRC_RULE_SEMANTIC_BREAKS[]
A function a release parses but answers differently, which the vocabulary cannot say.
constexpr DRC_CONSTRAINT_RENAME DRC_CONSTRAINT_RENAMES[]
bool SplitDrcRuleBlocks(const std::vector< DRC_RULE_TOKEN > &aTokens, std::vector< DRC_RULE_BLOCK > &aBlocks, wxString &aError)
Group the tokens into top-level blocks.
std::string DrcConstraintKindForTarget(const std::string &aKind, const DRC_RULE_VOCABULARY &aVocabulary)
The name the target reads a constraint kind by.
const DRC_RULE_VOCABULARY * FindDrcRuleVocabulary(const DOWNGRADE_TARGET &aTarget)
The vocabulary a target release could parse, generated from its release tags by tools/generate_drc_ru...
bool DrcRuleUnsupportedByTarget(const std::vector< DRC_RULE_TOKEN > &aTokens, const DRC_RULE_BLOCK &aBlock, const DRC_RULE_VOCABULARY &aVocabulary, std::vector< size_t > *aRenamed=nullptr)
True if the rule uses something the target's parser or evaluator cannot handle.
bool TokenizeDrcRules(const std::string &aText, std::vector< DRC_RULE_TOKEN > &aTokens, wxString &aError)
Tokenize with the lexer the rule readers use, so comments, strings and symbols end exactly where they...
DRC_RULES_FILTER_RESULT FilterDrcRulesForTarget(const wxString &aRulesText, const DOWNGRADE_TARGET &aTarget)
Filter a .kicad_dru file for the target.
constexpr DRC_RULE_VOCABULARY DRC_RULE_VOCABULARIES[]
@ DSN_LEFT
Definition dsnlexer.h:63
@ DSN_RIGHT
Definition dsnlexer.h:62
@ DSN_NUMBER
Definition dsnlexer.h:61
@ DSN_SYMBOL
Definition dsnlexer.h:60
@ DSN_COMMENT
Definition dsnlexer.h:56
@ DSN_STRING
Definition dsnlexer.h:64
@ DSN_EOF
Definition dsnlexer.h:65
#define _(s)
CITER next(CITER it)
Definition ptree.cpp:120
An older KiCad release we can export a project back to.
wxString m_id
Stable machine key for CLI and jobsets, e.g. "10.0".
wxString m_name
User-facing name, e.g. "KiCad 10.0".
A constraint kind renamed after a release. The release reads the same check by its old name.
wxString m_text
The filtered rules file text.
wxString m_error
Invalid source syntax, do not write m_text.
std::vector< wxString > m_dropped
Names of the rules the target cannot parse.
A top-level block of the rules file, as byte span and token range.
wxString m_name
The name after a "rule" head, for the report.
size_t m_start
Byte offset of the opening parenthesis.
size_t m_last
Index of the closing parenthesis token.
size_t m_first
Index of the opening parenthesis token.
size_t m_end
Byte offset just past the closing parenthesis.
std::string m_head
The word after the opening parenthesis, "rule" or "version".
std::string m_text
The token as the lexer reports it, strings without their quotes.
size_t m_offset
Byte offset of the token's first character in the source.
int m_type
A DSNLEXER token type.
Everything a rules file could name in one release.
VECTOR2I end
wxString result
Test unit parsing edge cases and error handling.