Comparison to relative LISP based languages (like Clojure)

[jasalt]

For onboarding lispers from other languages, it would be beneficial to provide documentation of the differences between Phel and (mainly) Clojure so that users could get up and running faster without having to discover the differences themselves.

Pretty good example in Basilisp ("Phel" for Python) docs "Differences from Clojure" https://basilisp.readthedocs.io/en/latest/differencesfromclojure.html

Some topics discussed there with few notes that came to my mind:

• Type Differences
• Arithmetic Comparison (note that PHP feature is "fixed" Avoid coercing nil to 0 in math operations phel-lang#887)
• Reader
  • Macros (syntax is like in Janet, plus auto-gensym like Clojure)
  • Regular Expressions (e.g. PHP regex uses surrounding slashes (?))
  • Special Forms (e.g. lambda syntax #(%) v.s. |($))
• Compilation
• Evaluation
• REPL
• Namespaces
• Core namespace differences (e.g. with-out-str v.s. with-output-buffer, no multi-methods)
• Core library equivalents (not much exist but might in future)
• Host Interop
• Concurrent Programming

More examples from ClojureScript https://www.clojurescript.org/about/differences and ClojureDart https://github.com/Tensegritics/ClojureDart/blob/main/doc/differences.md

[jasalt]

Snippet I've had in my notes regarding macros:

Macro syntax

| Clojure         | Phel 0.21.0+    | Notes                                               |
|-----------------+-----------------+-----------------------------------------------------|
| '               | '   quote       | quote item to not be evaluated / "opposite" to eval |
| `  syntax quote | `   quasiquote  |                                                     |
| ~               | ,               | unquote                                             |
| ~@              | ,@              | unquote-splicing                                    |
| name#           | name$           | auto-gensym                                         |

Notes:

• Phel doc calls syntax quote as quasiquote
• Phel discards gensym arguments: (gensym "FOOFO") ->__phel_1884

Links:

• https://phel-lang.org/documentation/macros/
• https://clojure-doc.org/articles/language/macros/
• https://robjohnson.dev/posts/clojure-macro-cheat-sheet/

[jasalt]

Another useful topic would be the differences in Phel's "iterable collections" or "sequences" / "seqs" as Clojure defines them (https://clojure.org/reference/sequences).

• Supported/unsupported Clojure sequence functions (support matrix?)
• Laziness
  • Broadly used in Clojure's sequence functions (e.g. map & filter)
  • Phel equivalents are often eager / non-lazy, though generator based "infinite sequences" used in repeat, repeatedly and iterate fns
• Other fundamental differences?

Major difference on basic level is non-laziness in Phel which needs to be taken into consideration to avoid running out of memory when handling large collections. Phel also lacks transducers which is more advanced feature.

Thought to add this here as it came up while reviewing doseq function PR phel-lang/phel-lang#1000

[Chemaclass]

Hey! Thought I'd share a quick update on where Phel stands compared to Clojure right now.

The Big News: Lazy Sequences Coming in v0.26! 🎉

In the current version (v0.25), sequences are eager by default - when you use map, filter, etc., they evaluate immediately. But this is changing in v0.26! We're making sequences lazy by default, just like Clojure. This means better performance with large collections and true infinite sequences.

If you're on v0.25 or earlier, just be aware that sequence operations are eager, so you need to watch memory usage with large collections.

Different Macro Syntax

We borrowed from Janet here:

• , instead of ~ for unquote
• ,@ instead of ~@ for unquote-splicing
• name$ instead of name# for auto-gensym

It feels natural once you get used to it!

Lambda Syntax

• Phel: |(+ $ 1)
• Clojure: #(+ % 1)

It's PHP Under The Hood

This means:

• Regex uses PHP patterns (with slashes)
• Phel interop is all PHP-based
• Some Clojure features not yet implemented (transducers, multi-methods)

What's Similar

The good news is a lot of Clojure knowledge transfers directly! The core ideas of immutability, functional programming, and REPL-driven development are all there. And with v0.26, lazy sequences will work just like you expect from Clojure.

What Would Help

I think a "Differences from Clojure" page (like Basilisp has) would be super helpful. We could include:

• Quick reference tables (like @jasalt's macro syntax table)
• PHP-specific patterns for host interop
• What's missing vs what's different