=============== Summary ===============

Change Set:        corruptSources
Date:            24 March 2022
Author:            Christoph Thiede

Revises comments, tests, and warnings about 'corrupt' or uncommon method sources.

1) Comments preceding a method selector no longer raise a parse error and thus do not trigger the source code validation in CodeHolders. This behavior was already existing for some versions; update the comment in Behavior>>#formalHeaderPartsFor: accordingly.
2) Add tests for Behavior>>#formalHeaderPartsFor: and Scanner>>#scanMessageParts:.
3) Rephrase the historic message in CodeHolder>>#informPossiblyCorruptSource and use #notify: instead of #inform: to honor the length of the message texts. See the postscript.

=============== Postscript ===============

"Postscript:"
Compiler evaluate: (CodeHolder commentsAt: #informPossiblyCorruptSource) last logged: false.

=============== Diff ===============

Behavior>>formalHeaderPartsFor: {accessing method dictionary} · ct 3/24/2022 19:27 (changed)
"popeye" formalHeaderPartsFor: "olive oil" aSelector
-     "RELAX!  The warning you may have just seen about possibly having a bad source file does not apply here, because this method *intends* to have its source code start with a comment.
-     This method returns a collection giving the parts in the formal declaration for aSelector.  This parse is in support of schemes in which adjutant properties of a method can be declared via special comments secreted in the formal header
+     "Answer a collection giving the parts in the formal declaration for aSelector.  This parse is in support of schemes in which adjutant properties of a method can be declared via special comments secreted in the formal header
    The result will have
         3 elements for a simple, argumentless selector.
        5 elements for a single-argument selector
        9 elements for a two-argument selector
        13 elements for a three-argument, selector
        etc...

    The syntactic elements are:

        1        comment preceding initial selector fragment

        2        first selector fragment
        3        comment following first selector fragment  (nil if selector has no arguments)

        ----------------------  (ends here for, e.g., #copy)

        4        first formal argument
        5        comment following first formal argument (nil if selector has only one argument)

        ----------------------  (ends here for, e.g., #copyFrom:)

        6        second keyword
        7        comment following second keyword
        8        second formal argument
        9        comment following second formal argument (nil if selector has only two arguments)

         ----------------------  (ends here for, e.g., #copyFrom:to:)

    Any nil element signifies an absent comment.
-     NOTE: The comment following the final formal argument is *not* successfully retrieved by this method in its current form, though it can be obtained, if needed, by other means (e.g. calling #firstPrecodeCommentFor:).  Thus, the *final* element in the structure returned by this method is always going to be nil."
+     NOTE: The comment following the final formal argument is *not* successfully retrieved by this method in its current form, though it can be obtained, if needed, by other means (e.g. calling #firstPrecodeCommentFor:).  Thus, the *final* element in the structure returned by this method is always going to be nil.
+     
+     NOTE:  This method *intends* to have its source code start with a comment. Try it out:
+         Behavior class formalHeaderPartsFor: #formalHeaderPartsFor:
+     "

-     ^ Scanner new scanMessageParts: (self methodHeaderFor: aSelector)
- 
- "
-     Behavior class formalHeaderPartsFor: #formalHeaderPartsFor:
- "
- 
- 
-     
+     ^ Scanner new scanMessageParts: (self methodHeaderFor: aSelector)

BehaviorTest>>testFormalHeaderParts {tests} · ct 3/24/2022 19:22
+ testFormalHeaderParts
+ 
+     self
+         assert: #('popeye' 'formalHeaderPartsFor:' 'olive oil' 'aSelector' nil)
+         equals: (self class class formalHeaderPartsFor: #formalHeaderPartsFor:) asArray.
+     
+     CurrentReadOnlySourceFiles cacheDuring: [
+         Object selectorsDo: [:selector | | parts |
+             parts := Object formalHeaderPartsFor: selector.
+             self assert: (selector numArgs * 4 + 1 max: 3) equals: parts size.
+             selector keywords withIndexDo: [:keyword :index |
+                 self assert: keyword equals: (parts at: index * 4 - 2)]]].

Browser>>informUnknownPackage {system category functions} · mt 3/14/2022 13:17 (changed)
informUnknownPackage

-     self inform: ('The category <b>{1}</b> does not<br>belong to a known package.' translated format: {self selectedSystemCategory}) asTextFromHtml.
+     self inform: ('The category <b>{1}</b> does not belong to a known package.' translated format: {self selectedSystemCategory}) asTextFromHtml.

CodeHolder>>informPossiblyCorruptSource {misc} · ct 3/24/2022 19:51 (changed)
informPossiblyCorruptSource
+     self
+         notify: ('There may be a problem with your sources files!

-     | sourcesName |
-     sourcesName := FileDirectory localNameFor: Smalltalk sourcesName.
-     self inform: 'There may be a problem with your sources file!
+ The source code for every method should (usually) start with the method selector but this is not the case with this method! You may proceed with caution but it is recommended that you get a new source file and check your changes file for corruptions.

- The source code for every method should (usually) start with the
- method selector but this is not the case with this method! You may
- proceed with caution but it is recommended that you get a new source file.
+ A common cause for this problem are softwares that manipulate the line endings of the "{1}" file or your "{2}" file. Make sure to treat these files as binary files to preserve the CR line endings when sharing, compressing/decompressing (for instance, via Mac Stuffit Expander), or synchronizing (for instance, via git or Microsoft OneDrive) them.

- This can happen if you download the "' , sourcesName  , '" file, 
- or the ".changes" file you use, as TEXT. It must be transfered 
- in BINARY mode, even if it looks like a text file, 
- to preserve the CR line ends.
+ (Occasionally, methods may break this rule legitimately -- for example, {1} uses this for testing.  In such rare cases, you can happily disregard this warning.)' translated format: {FileDirectory localNameFor: Smalltalk sourcesName. FileDirectory localNameFor: Smalltalk changesName. thisContext method asCodeReference asString})

- Mac users: This may have been caused by Stuffit Expander. 
- To prevent the files above to be converted to Mac line ends 
- when they are expanded, do this: Start the program, then 
- from Preferences... in the File menu, choose the Cross 
- Platform panel, then select "Never" and press OK. 
- Then expand the compressed archive again.
- 
- (Occasionally, the source code for a method may legitimately
- start with a non-alphabetic character -- for example, Behavior
- method #formalHeaderPartsFor:.  In such rare cases, you can
- happily disregard this warning.)'
+     "
+         CodeHolder >> #informPossiblyCorruptSource in: [:method | | lines |
+             lines := method getSource asString lines.
+             method properties at: #source put:
+                 ((lines allButFirst copyWithFirst: (lines first , ': <fake arg, remove before recompile>'))
+                     joinSeparatedBy: String cr)]
+     "

ScannerTest>>testScanMessageParts {tests} · ct 3/24/2022 19:08
+ testScanMessageParts
+ 
+     self
+         assert: #('popeye' 'formalHeaderPartsFor:' 'olive oil' 'aSelector' nil)
+         equals: (Scanner new scanMessageParts: '"popeye" formalHeaderPartsFor: "olive oil" aSelector') asArray.

["corruptSources.1.cs"]

---
Sent from Squeak Inbox Talk
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220324/e849539a/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: corruptSources.1.cs
Type: application/octet-stream
Size: 5214 bytes
Desc: not available
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20220324/e849539a/attachment.obj>