Jamie Balfour

Welcome to my personal website.

Find out more about me, my personal projects, reviews, courses and much more here.

Official ZPE/YASS documentationStream

UseMathjax(false);?> Introduction Stream object functions constructor open read has_next skip write_to_file close is_open length position content_type source Byte chunks Examples Introduction The Stream object provides sequential access to binary data from a local file or an HTTP or HTTPS address. Data can be read in chunks, skipped, or written directly to a file without first loading the entire source into memory. The Stream object was introduced in ZPE 1.14.9. It is suitable for large resources such as videos, audio files, archives and other binary downloads. A source can be supplied to the constructor or opened later using open. Both operations require permission level 4. Writing the remaining stream to a file also requires permission level 4. All other functions require permission level 0. Online sources must use a normal http:// or https:// address. A browser blob: address cannot be opened because it only refers to data held inside the browser that created it. Stream object functions The following is a list of the native functions exposed by the Stream object. Stream(string source) ⇒ Stream Creates a Stream and opens source. The source can be a local filename or an HTTP or HTTPS address. open(string source) ⇒ boolean Closes any previously opened source, then opens source. Returns true when the source was opened successfully, or false when it could not be opened. The stream position is reset to 0. read(number size) ⇒ ByteListObject Reads up to size bytes and returns them as a ByteListObject. The size must be between 1 byte and 16 MiB. The returned chunk can contain fewer bytes when the end of the source is reached. has_next() ⇒ boolean Returns true when more data is available. This check does not advance the stream position. skip(number size) ⇒ number Skips up to size bytes and returns the number of bytes actually skipped. The size cannot be negative. write_to_file(string file) ⇒ number Writes all remaining stream data to file and returns the number of bytes written. An existing file is overwritten. If data has already been read or skipped, only the data after the current position is written. close() ⇒ boolean Closes the stream and disconnects an HTTP connection when one is in use. Returns true when the stream was closed successfully. is_open() ⇒ boolean Returns true while the underlying stream remains open. This is independent of whether unread data remains; use has_next to test for more data. length() ⇒ number Returns the total source length in bytes. Returns -1 when the length is not known, which can occur when an online server does not provide a content length. position() ⇒ number Returns the number of bytes read, skipped or written from the current source. content_type() ⇒ string Returns the source's MIME type, such as video/mp4. Returns an empty string when the type could not be determined. source() ⇒ string Returns the local filename or online address supplied to the most recent call to the constructor or open. Byte chunks The read function returns a ByteListObject. It exposes the following functions: length() ⇒ number Returns the number of bytes in the chunk. get(number index) ⇒ number Returns the byte at index. Byte values use the signed range from -128 to 127. print_list() ⇒ list Converts the byte chunk into a standard YASS list of numbers. Examples Reading an online video in chunks: YASS $url = "https://www.jamiebalfour.scot/public/sleep-learning.mp4" $stream = new Stream($url) print($stream->content_type()) print($stream->length()) while ($stream->has_next()) $chunk = $stream->read(65536) print($chunk->length()) end $stream->close() Downloading an online resource directly to a file: YASS $url = "https://www.jamiebalfour.scot/public/sleep-learning.mp4" $stream = new Stream($url) $written = $stream->write_to_file("sleep-learning.mp4") print("Downloaded " & $written & " bytes.") $stream->close() Reading part of a local file: YASS $stream = new Stream("archive.zip") $stream->skip(128) $chunk = $stream->read(1024) print($chunk->print_list()) print($stream->position()) $stream->close() Notes: Sequential access: Stream does not seek backwards. Reopen the source to return to the beginning. Partial reads: read may return fewer bytes than requested, especially near the end of a source. HTTP behaviour: Redirects are followed and ZPE uses connection and read timeouts for online sources. File output: write_to_file consumes the remaining stream.
Back to documentation
Comments

There are no comments on this page.

New comment

Comments are welcome and encouraged, including disagreement and critique. However, this is not a space for abuse. Disagreement is welcome; personal attacks, harassment, or hate will be removed instantly. This site reflects personal opinions, not universal truths. If you can’t distinguish between the two, this probably isn’t the place for you. The system temporarily stores IP addresses and browser user agents for the purposes of spam prevention, moderation, and safeguarding. This data is automatically removed after fourteen days. Your email address is stored so that replies can be sent to your email address.

Comments powered by BalfComment

Loading
Code previewClose
!
Feedback 👍
Comments are sent via email to me.