Migration from Pharo 6.1 to Pharo 7.0 guideline¶
Pharo 7 file streams guideline¶
Since version 5, Pharo provides a new file streams API that deprecates the one based on classes
like FileStream or MultiByteBinaryOrTextStream. In Pharo 7 this deprecated API was removed from the kernel.
Key points¶
- use file references as entry points to file streams
- do not use the
FileStreamclass 'file.txt' asFileReference readStreamand similar methods now return an instance ofZnCharacterReadStreaminstead ofMultiByteFileStream'file.txt' asFileReference writeStreamand similar methods now return an instance ofZnCharacterWriteStreaminstead ofMultiByteFileStream- the new API has a clearer separation between binary and text files
Code conversion¶
This section shows the most common examples of file streams. For simplicity, errors are not handled.
Force creation of a new file and write a UTF-8 text¶
obsolete code¶
new code¶
Read UTF-8 text from an existing file¶
obsolete code¶
new code¶
Get all content of existing UTF-8 file¶
obsolete code¶
(FileStream readOnlyFileNamed: '1.txt') contentsOfEntireFile.
```
##### new code
```smalltalk
'1.txt' asFileReference readStream upToEnd.
Force creation of a new file and write binary data into it¶
obsolete code¶
new code¶
'1.bin' asFileReference ensureDelete;
binaryWriteStreamDo: [ :stream | stream nextPutAll: #[1 2 3] ].
Read binary data from an existing file¶
obsolete code¶
new code¶
Force creation of a new file with a different encoding¶
obsolete code¶
FileStream forceNewFileNamed: '2.txt' do: [ :stream |
stream converter: (TextConverter newForEncoding: 'cp-1250').
stream nextPutAll: 'Příliš žluťoučký kůň úpěl ďábelské ódy.' ].
new code¶
('2.txt' asFileReference) ensureDelete;
writeStreamEncoded: 'cp-1250' do: [ :stream |
stream nextPutAll: 'Příliš žluťoučký kůň úpěl ďábelské ódy.' ].
Read encoded text from an existing file¶
obsolete code¶
FileStream readOnlyFileNamed: '2.txt' do: [ :stream |
stream converter: (TextConverter newForEncoding: 'cp-1250').
stream upToEnd ].
new code¶
Write a UTF-8 text to STDOUT¶
obsolete code¶
new code¶
Write CP-1250 encoded text to STDOUT¶
obsolete code¶
FileStream stdout
converter: (TextConverter newForEncoding: 'cp-1250');
nextPutAll: 'Příliš žluťoučký kůň úpěl ďábelské ódy.'; lf.
new code¶
(ZnCharacterWriteStream on: Stdio stdout encoding: 'cp1250')
nextPutAll: 'Příliš žluťoučký kůň úpěl ďábelské ódy.'; lf;
flush.
Read a UTF-8 text from STDIN¶
CAUTION: The following code will block your VM until input on STDIN is provided!
obsolete code¶
new code¶
Write binary data to STDOUT¶
obsolete code¶
new code¶
Read binary data from STDIN¶
CAUTION: The following code will block your VM until input on STDIN is provided!
obsolete code¶
new code¶
Positionable streams¶
The message #position: always works at the binary level, not at the character level.
This will lead to an error (ZnInvalidUTF8: Illegal leading byte for utf-8 encoding) in case of the file created above, because we set the position into the middle of a UTF-8 encoded character. To be safe, you need to read the file from the beginning.
Buffering¶
The MultiByteFileStream was buffered. If you create a stream using the expression
then the ZnCharacterReadStream is not created directly on top of the stream but on top of a buffered stream
that uses the file stream internally.
If you create a ZnCharacterReadStream directly on the file stream, then the characters from the file are read
one by one which may be about ten times slower!
Binary streams do not understand #<< message anymore¶
Binary streams used to understand #<< message in the past, but not anymore. One should either use #next: or #nextPutAll:.