Merge pull request #148 from chr1st0scli/streams

Support infinite streams.

Author: chr1st0scli

CHANGELOG.md

@@ -16,6 +16,23 @@ Semantic versioning is followed.
 
 ### Removed
 
+## [1.4.0] - 2025-02-16
+
+### Added
+- `delay` special form for supporting delayed expressions.
+- `force` library procedure to force the evaluation of a delayed expression.
+- `cons-stream` derived expression for creating infinite streams.
+- `cdr-stream` library procedure to enable walking through a stream.
+- `make-range-stream` library procedure to make a numerical range stream.
+- `map-stream` library procedure that projects elements of a stream.
+- `filter-stream` library procedure that filters elements of a stream.
+
+### Fixed
+
+### Changed
+
+### Removed
+
 ## [1.3.0] - 2024-06-30
 
 ### Added

RainLisp/AbstractSyntaxTree/Delay.cs

@@ -0,0 +1,32 @@
+using RainLisp.Evaluation;
+using RainLisp.Evaluation.Results;
+
+namespace RainLisp.AbstractSyntaxTree
+{
+    /// <summary>
+    /// Delayed expression in the abstract syntax tree.
+    /// </summary>
+    public class Delay : Expression
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="Delay"/> class.
+        /// </summary>
+        /// <param name="delayed">The expression whose evaluation is meant to be delayed.</param>
+        public Delay(Expression delayed)
+            => Delayed = delayed;
+
+        /// <summary>
+        /// Gets ot sets the expression whose evaluation is meant to be delayed.
+        /// </summary>
+        public Expression Delayed { get; init; }
+
+        /// <summary>
+        /// Evaluates the delay expression and returns the result.
+        /// </summary>
+        /// <param name="visitor">The visitor that implements the evaluation.</param>
+        /// <param name="environment">The environment the evaluation occurs in.</param>
+        /// <returns>The result of the evaluation.</returns>
+        public override EvaluationResult AcceptVisitor(IEvaluatorVisitor visitor, IEvaluationEnvironment environment)
+            => visitor.EvaluateDelay(this, environment);
+    }
+}

RainLisp/DerivedExpressions/ConsStream.cs

@@ -0,0 +1,31 @@
+using RainLisp.AbstractSyntaxTree;
+
+namespace RainLisp.DerivedExpressions
+{
+    /// <summary>
+    /// Cons stream expression as described in the syntax grammar.
+    /// </summary>
+    public class ConsStream
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ConsStream"/> class.
+        /// </summary>
+        /// <param name="first">The first constituent expression.</param>
+        /// <param name="second">The second constituent expression.</param>
+        public ConsStream(Expression first, Expression second)
+        {
+            First = first;
+            Second = second;
+        }
+
+        /// <summary>
+        /// Gets or sets the first constituent expression.
+        /// </summary>
+        public Expression First { get; init; }
+
+        /// <summary>
+        /// Gets or sets the second constituent expression.
+        /// </summary>
+        public Expression Second { get; init; }
+    }
+}

RainLisp/DerivedExpressions/Transformations.cs

@@ -1,4 +1,5 @@
 using RainLisp.AbstractSyntaxTree;
+using RainLisp.Grammar;
 
 namespace RainLisp.DerivedExpressions
 {
@@ -96,6 +97,15 @@ public static Expression ToIf(this Or or)
             return AndOrToNestedIf(or.Expressions, CreateIfForOr);
         }
 
+        /// <summary>
+        /// Converts a cons stream expression to an application of the cons primitive procedure on the first and the delayed second
+        /// constituent parts of the cons stream in the abstract syntax tree.
+        /// </summary>
+        /// <param name="consStream">The cons stream to convert.</param>
+        /// <returns>An application of the cons primitive procedure on the first and the delayed second expressions.</returns>
+        public static Application ToConsOnFirstAndDelayedSecond(this ConsStream consStream)
+            => new Application(new Identifier(Primitives.CONS), new[] { consStream.First, new Delay(consStream.Second) });
+
         private static Expression CreateIfForAnd(Expression expression, Expression nestedExpression)
             // The current and's operand becomes the if's predicate, the rest operands go inside
             // the consequent as a a nested expression and the alternative is always false.

RainLisp/Docs/common-libraries.md

@@ -1,4 +1,7 @@
 # Common Libraries
+
+Common libraries are procedures that are defined in the language itself.
+
 ## List Operations
 - [append](common-libraries/append.md)
 - [filter](common-libraries/filter.md)
@@ -10,6 +13,13 @@
 - [reduce](common-libraries/reduce.md)
 - [reverse](common-libraries/reverse.md)
 
+## Stream Operations
+- [cdr-stream](common-libraries/cdr-stream.md)
+- [filter-stream](common-libraries/filter-stream.md)
+- [force](common-libraries/force.md)
+- [make-range-stream](common-libraries/make-range-stream.md)
+- [map-stream](common-libraries/map-stream.md)
+
 ## car & cdr Flavors
 - [cddr](common-libraries/cddr.md)
 - [cadr](common-libraries/cadr.md)

RainLisp/Docs/common-libraries/cdr-stream.md

@@ -0,0 +1,12 @@
+# cdr-stream
+```scheme
+(define (cdr-stream stream)
+  (force (cdr stream)))
+```
+Returns the rest of a stream, i.e. its next element by forcing its promise to be fulfilled and a promise for the rest of it.
+
+## Example
+```scheme
+(cdr-stream (make-range-stream 1 8000000))
+```
+-> *(2 . [UserProcedure] Parameters: 0)*

RainLisp/Docs/common-libraries/filter-stream.md

@@ -0,0 +1,35 @@
+# filter-stream
+```scheme
+(define (filter-stream predicate stream)
+  (cond ((null? stream) nil)
+        ((predicate (car stream))
+         (cons-stream (car stream) (filter-stream predicate (cdr-stream stream))))
+        (else (filter-stream predicate (cdr-stream stream)))))
+```
+Returns a new stream containing the first element of a stream that satisfies a condition and a promise for the rest of them.
+
+> *predicate* is a procedure accepting a single argument (each element of *stream* at a time) and its result is evaluated as a boolean.
+
+> *stream* is the stream to filter.
+
+## Examples
+```scheme
+; Filter the even numbers of a stream.
+; It returns the first even number and a promise to filter the rest of them.
+(filter-stream
+  (lambda (n) (= 0 (% n 2)))
+  (make-range-stream 1 8))
+```
+-> *(2 . [UserProcedure] Parameters: 0)*
+
+```scheme
+; Create a stream of evens.
+(define evens
+  (filter-stream
+    (lambda (n) (= 0 (% n 2)))
+    (make-range-stream 1 8)))
+
+; Find the second even.
+(car (cdr-stream evens))
+```
+-> *4*

RainLisp/Docs/common-libraries/force.md

@@ -0,0 +1,15 @@
+# force
+```scheme
+(define (force proc)
+  (proc))
+```
+Executes a procedure and returns its result. Typically the procedure is a promise, i.e. a delayed expression
+that results from [delay](../special-forms-derived-expressions/delay.md).
+
+> *proc* is the procedure to execute, typically a promise to evaluate an expression.
+
+## Example
+```scheme
+(force (delay 4))
+```
+-> *4*

RainLisp/Docs/common-libraries/make-range-stream.md

@@ -0,0 +1,20 @@
+# make-range-stream
+```scheme
+(define (make-range-stream start end)
+  (if (> start end)
+      nil
+      (cons-stream start (make-range-stream (+ start 1) end))))
+```
+Returns a new stream of numeric values ranging from *start* until *end*. The first numeric value is evaluated and the evaluation of the rest is deferred,
+i.e. delayed until explicitly requested. If *start* is greater than *end*, [nil](../primitives/nil.md) is returned.
+
+> *start* is the first value of the stream which is immediately evaluated.
+
+> *end* is the last value of the stream.
+
+## Example
+```scheme
+; Returns a stream made of the first element and a promise to fulfill the rest of it.
+(make-range-stream 7 5000000)
+```
+-> *(7 . [UserProcedure] Parameters: 0)*

RainLisp/Docs/common-libraries/map-stream.md

@@ -0,0 +1,34 @@
+# map-stream
+```scheme
+(define (map-stream proc stream)
+  (if (null? stream)
+      nil
+      (cons-stream (proc (car stream)) (map-stream proc (cdr-stream stream)))))
+```
+Returns a new stream with the projection of the first element and a promise for the projection of the rest of them.
+
+> *proc* is a procedure accepting a single argument (each element of *stream* at a time) and returning a projection.
+
+> *stream* is the delayed list whose each element is mapped to another one on demand.
+
+## Examples
+```scheme
+; Multiply each number in a stream by 10.
+; It returns the projected first element and a promise to project the rest of them.
+(map-stream 
+  (lambda (n) (* n 10))
+  (make-range-stream 1 5))
+```
+-> *(10 . [UserProcedure] Parameters: 0)*
+
+```scheme
+; Create a stream of multiples of 10.
+(define projected-stream
+  (map-stream 
+    (lambda (n) (* n 10))
+    (make-range-stream 1 5)))
+
+; Project the second element.
+(car (cdr-stream projected-stream))
+```
+-> *20*

RainLisp/Docs/primitives.md

@@ -1,4 +1,7 @@
 # Primitives
+
+Primitives are procedures or semantics that require some kind of support from the underlying platform.
+
 - [+](primitives/plus.md)
 - [-](primitives/minus.md)
 - [*](primitives/multiply.md)

RainLisp/Docs/special-forms-derived-expressions.md

@@ -6,7 +6,9 @@ syntactic sugar, i.e. reserved keywords that are transformed to equivalent speci
 - [and](special-forms-derived-expressions/and.md)
 - [begin](special-forms-derived-expressions/begin.md)
 - [cond](special-forms-derived-expressions/cond.md)
+- [cons-stream](special-forms-derived-expressions/cons-stream.md)
 - [define](special-forms-derived-expressions/define.md)
+- [delay](special-forms-derived-expressions/delay.md)
 - [if](special-forms-derived-expressions/if.md)
 - [lambda](special-forms-derived-expressions/lambda.md)
 - [let](special-forms-derived-expressions/let.md)

RainLisp/Docs/special-forms-derived-expressions/cons-stream.md

@@ -0,0 +1,39 @@
+# cons-stream
+A derived expression for constructing a stream, i.e. a pair of an immediately evaluated expression and a delayed one.
+```
+(cons-stream expression expression)
+```
+
+The first expression is evaluated immediately and the second one is delayed. The result of the `cons-stream` expression
+is a pair made of the value of the first expression and a procedure which evaluates the second one when called, i.e. a promise.
+
+## Examples
+```scheme
+(cons-stream 1 2)
+```
+-> *(1 . [UserProcedure] Parameters: 0)*
+
+```scheme
+; Assign the procedure to a variable and call it later.
+(define delayed (cdr (cons-stream 1 2)))
+(delayed)
+```
+-> *2*
+
+```scheme
+; Use the force library procedure to force the evaluation.
+(force (cdr (cons-stream 1 2)))
+```
+-> *2*
+
+```scheme
+; Use the cdr-stream library procedure to force the evaluation.
+(cdr-stream (cons-stream 1 2))
+```
+-> *2*
+
+## Remarks
+> Note that `(cons-stream a b)` is syntactic sugar for `(cons a (delay b))`.
+
+> Note that the procedure created for the delayed expression is a memoized one. I.e. the expression is evaluated once
+when needed and subsequent calls will simply return the previously calculated value.

RainLisp/Docs/special-forms-derived-expressions/delay.md

@@ -0,0 +1,35 @@
+# delay
+A special form that delays the evaluation of the given expression, effectively creating a promise to evaluate it in the future.
+The evaluation result is a procedure which evaluates the expression when called.
+```
+(delay expression)
+```
+
+## Examples
+```scheme
+; Delay displaying "Hello World!".
+(delay (display "Hello World!"))
+```
+-> *[UserProcedure] Parameters: 0*
+
+```scheme
+; Assign the procedure to a variable and call it later.
+(define delayed (delay (display "Hello World!")))
+(delayed)
+```
+-> *Hello World!*
+
+```scheme
+; Use the force library procedure to force the evaluation.
+(force (delay (display "Hello World!")))
+```
+-> *Hello World!*
+
+## Remarks
+
+> `(delay a)` is equivalent to `(lambda() a)`. So, it needs to be a special form; otherwise `(delay a)`
+would cause `a` to be evaluated before calling `delay` on it, due to the language's applicative order of evaluation
+which dictates that arguments are evaluated first before applying a procedure on them.
+
+> Note that the procedure created for the delayed expression is a memoized one. I.e. the expression is evaluated once
+when needed and subsequent calls will simply return the previously calculated value.

RainLisp/Evaluation/EvaluatorVisitor.cs

@@ -192,6 +192,21 @@ public EvaluationResult EvaluateBody(Body body, IEvaluationEnvironment environme
             return EvaluateSequence(body.Expressions, environment);
         }
 
+        /// <summary>
+        /// Returns the result of evaluating a delay.
+        /// </summary>
+        /// <param name="delay">The delay to evaluate.</param>
+        /// <param name="environment">The environment which the evaluation occurs in.</param>
+        /// <returns>The result of the evaluation.</returns>
+        public EvaluationResult EvaluateDelay(Delay delay, IEvaluationEnvironment environment)
+        {
+            // An expression is delayed by simply putting it in a procedure body that will be called later.
+            var body = new Body(null, new List<Expression> { delay.Delayed });
+
+            // A memoized user procedure caches the result of its first evaluation.
+            return new MemoizedUserProcedure(null, body, environment);
+        }
+
         /// <summary>
         /// Returns the result of evaluating a program. The evaluation occurs lazily on a per request basis, while the return value is being enumerated.
         /// </summary>

RainLisp/Evaluation/IEvaluatorVisitor.cs

@@ -110,6 +110,14 @@ public interface IEvaluatorVisitor
         /// <exception cref="EvaluationException">An error occurs during the evaluation of the <paramref name="body"/>.</exception>
         EvaluationResult EvaluateBody(Body body, IEvaluationEnvironment environment);
 
+        /// <summary>
+        /// Returns the result of evaluating a delay.
+        /// </summary>
+        /// <param name="delay">The delay to evaluate.</param>
+        /// <param name="environment">The environment which the evaluation occurs in.</param>
+        /// <returns>The result of the evaluation.</returns>
+        EvaluationResult EvaluateDelay(Delay delay, IEvaluationEnvironment environment);
+
         /// <summary>
         /// Returns the result of evaluating a program. The evaluation occurs lazily on a per request basis, while the return value is being enumerated.
         /// </summary>