Merge pull request #4291 from Chemaclass/master

[phel/en] Add phel.html

1 files changed, 337 insertions, 0 deletions

diff --git a/phel.html.markdown b/phel.html.markdown
new file mode 100644
index 00000000..4dc030fa
--- /dev/null
+++ b/phel.html.markdown
@@ -0,0 +1,337 @@
+---
+language: phel
+filename: learnphel.phel
+contributors:
+    - ["Chemaclass", "https://github.com/Chemaclass"]
+---
+
+[Phel](https://phel-lang.org/) is a functional programming language that compiles to PHP.
+It is a dialect of Lisp inspired by Clojure and Janet.
+
+## Features
+- Built on PHP's ecosystem
+- Good error reporting
+- Persistent Datastructures (Lists, Vectors, Maps and Sets)
+- Macros
+- Recursive functions
+- Powerful but simple Syntax
+- REPL
+
+```newlisp
+# Comments begin with a # character and continue until the end of the line. There are no multi-line comments.
+
+# Phel is written in "forms", which are just
+# lists of things inside parentheses, separated by whitespace.
+
+# The first call in a file should be ns, to set the namespace
+(ns learn-phel)
+
+# More basic examples:
+
+# str will create a string out of all its arguments
+(str "Hello" " " "World") #=> "Hello World"
+
+# Math is straightforward
+(+ 1 1) #=> 2
+(- 2 1) #=> 1
+(* 1 2) #=> 2
+(/ 2 1) #=> 2
+
+# Equality is =
+(= 1 1) #=> true
+(= 2 1) #=> false
+
+# You need not for logic, too
+(not true) #=> false
+
+# Nesting forms works as you expect
+(+ 1 (- 3 2)) # = 1 + (3 - 2) => 2
+
+# Phel inherits PHP under the hood, so it can use native PHP (functions and classes) without 
+# any additional cost by using the `php/` prefix to all PHP native functions.
+
+# Types
+#############
+
+# Booleans are similar as the native PHP ones
+
+nil
+true
+false 
+
+# Symbols are used to name functions and variables in Phel
+# For example: symbol, snake_case_symbol, my-module/my-function
+
+# Keywords are like symbols that begin with a colon character. However, they are used as constants rather than a name for something.
+
+:keyword
+:0x0x0x
+::
+
+# Numbers in Phel are equivalent to numbers in PHP
+
+1337 # integer
++1337 # positive integer
+-1337 # negative integer
+
+1.234 # float
++1.234 # positive float
+-1.234 # negative float
+1.2e3 # float
+7E-10 # float
+
+# Strings are surrounded by double quotes. They almost work the same as PHP double quoted strings.
+# A string can be written in multiple lines. The line break character is then ignored by the reader.
+
+"hello world"
+
+"this is\na\nstring"
+
+"this
+is
+a
+string."
+
+"use backslack to escape \" string"
+
+"the dollar must not be escaped: $ or $abc just works"
+
+
+# Collections & Sequences
+#############
+
+# Lists are linked-list data structures, while vectors are array-backed
+(type '(1 2 3)) #=> :list
+(type [1 2 3])  #=> :vector
+
+# A list would be written as just (1 2 3), but we have to quote
+# it to stop the reader thinking it's a function.
+# Also, (list 1 2 3) is the same as '(1 2 3)
+
+# You can produce a (non-lazy) sequence between a range. 
+(range 1 10 2) #=> (range from to step)
+(take 4 (range 10))
+
+# Use cons to add an item to the beginning of a list
+(cons 4 '(1 2 3)) #=> (4 1 2 3)
+
+# Use push to add, and put to replace an item in a vector 
+(push [1 2 3] 4)  #=> (1 2 3 4)
+(put [1 2 3] 1 4) #=> (1 4 3)
+
+# Use concat to add lists or vectors together
+(concat [1 2] '(3 4)) #=> [1 2 3 4]
+
+# Use filter, map to interact with collections
+(map inc [1 2 3])      #=> [2 3 4]
+(filter even? [1 2 3]) #=> [2]
+
+# Use reduce to reduce them. The initial-value is mandatory
+(reduce + 0 [1 2 3 4])
+#=> (+ (+ (+ 1 2) 3) 4)
+#=> 10
+
+(reduce push [] '(3 2 1))
+#=> (push (push (push [] 3) 2) 1)
+#=> [3 2 1]
+
+# Functions
+#############
+
+# Use fn to create new functions
+# A function always returns its last statement
+(fn [] "Hello World") #=> <function>
+
+# You need extra parens to call it
+((fn [] "Hello World")) #=> "Hello World"
+
+# You can bind a value to a symbol using def for definition
+(def x 1)
+x #=> 1
+
+# Variables provide a way to manage mutable state
+(def foo (var 10)) # Define a variable with value 10
+
+# Assign a function to a definition
+(def hello-world (fn [] "Hello World"))
+(hello-world) #=> "Hello World"
+
+# You can shorten this process by using defn
+(defn hello-world [] "Hello World")
+
+# The [] is the list of arguments for the function
+(defn hello [name]
+  (str "Hello " name))
+(hello "Jens") #=> "Hello Jens"
+
+# You can also use this shorthand to create functions
+(def hello2 |(str "Hello " $1))
+(hello2 "Anna") #=> "Hello Anna"
+
+# Functions can pack extra arguments up in a seq for you
+(defn count-args [& args]
+  (str "You passed " (count args) " args: " args))
+(count-args 1 2 3) #=> "You passed 3 args: @[1 2 3]"
+
+# You can mix regular and packed arguments
+(defn hello-count [name & args]
+  (str "Hello " name ", you passed " (count args) " extra args"))
+(hello-count "Jesus" 1 2) #=> "Hello Jesus, you passed 2 extra args"
+
+
+# Maps
+#############
+
+# Hash maps have faster lookups but don't retain key order
+(type {:a 1 :b 2 :c 3})          #=> :hash-map
+(type (hash-map :a 1 :b 2 :c 3)) #=> :hash-map
+
+# Maps can use any hashable type as a key, but usually keywords are best
+# Keywords are like strings with some efficiency bonuses and they start with `:`
+(type :a) #=> :keyword
+
+(def stringmap {"a" 1 "b" 2 "c" 3})
+stringmap  #=> {"a" 1 "b" 2 "c" 3}
+
+(def keymap {:a 1 :b 2 :c 3})
+keymap  #=> {:a 1 :c 3 :b 2}
+
+# Retrieve a value from a map by calling it as a function
+(stringmap "a") #=> 1
+(keymap :a)     #=> 1
+
+# Keywords can be used to retrieve their value from a map, too!
+(:b keymap) #=> 2
+
+# Don't try this with strings
+# ("a" stringmap)
+# ...Exception: Call to undefined function a()
+
+# Retrieving a non-present key returns nil
+(stringmap "d") #=> nil
+
+# Use put to add new keys to hash-maps
+(def newkeymap (put keymap :d 4))
+newkeymap #=> {:a 1 :b 2 :c 3 :d 4}
+
+# But remember, phel types are immutable!
+keymap #=> {:a 1 :b 2 :c 3}
+
+# Use unset to remove keys
+(unset keymap :a) #=> {:b 2 :c 3}
+
+# Sets
+#############
+
+# A Set contains unique values in random order
+
+(type (set 1 2 3)) #=> :set
+(set 1 2 3 1 2 3 3 2 1 3 2 1) #=> (set 1 2 3)
+
+# Add a member with push
+(push (set 1 2 3) 4) #=> (set 1 2 3 4)
+
+# Remove one with unset
+(unset (set 1 2 3) 1) #=> (set 2 3)
+
+# Test for existence by using the set as a function
+((set 1 2 3) 1) #=> 1
+((set 1 2 3) 4) #=> nil
+
+# There are more functions like: count, union, intersection, difference, etc
+
+
+# Useful forms
+#############
+
+# `If` conditionals in phel are special forms
+(if false "a" "b") #=> "b"
+(if false "a") #=> nil
+
+# Use let to create temporary bindings
+(let [a 1 b 2]
+  (> a b)) #=> false
+
+# Group statements together with do
+(do
+  (print "Hello")
+  "World") #=> "World" (prints "Hello")
+
+# Functions have an implicit do
+(defn print-and-say-hello [name]
+  (print "Saying hello to " name)
+  (str "Hello " name))
+(print-and-say-hello "Jeff") #=> "Hello Jeff" (prints "Saying hello to Jeff")
+
+# So does let
+(let [name "Urkel"]
+  (print "Saying hello to " name)
+  (str "Hello " name)) #=> "Hello Urkel" (prints "Saying hello to Urkel")
+
+# Use the threading macros (-> and ->>) to express transformations of
+# data more clearly.
+
+# The "Thread-first" macro (->) inserts into each form the result of
+# the previous, as the first argument (second item)
+(->
+   {:a 1 :b 2}
+   (put :c 3)  #=> (put {:a 1 :b 2} :c 3)
+   (unset :b)) #=> (unset (put {:a 1 :b 2} :c 3) :b)
+
+
+# The double arrow does the same thing, but inserts the result of
+# each line at the *end* of the form. This is useful for collection
+# operations in particular:
+(->>
+   (range 10)
+   (map inc)      #=> (map inc (range 10))
+   (filter odd?)) #=> (filter odd? (map inc (range 10)))
+                  # Result: [1 3 5 7 9]
+
+
+# When you are in a situation where you want more freedom as where to
+# put the result of previous data transformations in an
+# expression, you can use the as-> macro. With it, you can assign a
+# specific name to transformations' output and use it as a
+# placeholder in your chained expressions:
+
+(as-> [1 2 3] input
+  (map inc input)     #=> You can use last transform's output at the last position
+  (get input 2)       #=> and at the second position, in the same expression
+  (push [4 5 6] input 8 9 10)) #=> or in the middle !
+                               # Result: [4 5 6 4 8 9 10]
+
+# PHP
+#################
+
+# PHP has a huge and useful standard library, and you're able to use
+# all native functions with the prefix `php/`.
+(php/+ 1 2 3)
+
+# With :use you can use different namespaces. Similar as `use` in PHP
+(ns my\module
+  (:use \DateTimeImmutable))
+
+# You can import functions from other phel files with :require
+(ns my\module
+  (:require phel\test :refer [deftest is]))
+
+# Use the class name with a "php/new" to make a new instance
+(php/new \DateTime) # <a date-time object>
+
+# Use php/-> to call methods of an object
+(def d (php/new \DateTime))
+(php/-> d (getTimestamp)) # <a timestamp>
+
+# you can do it in one line too
+(php/-> (php/new \DateTime) (getTimestamp))
+
+# Use php/:: to call static methods
+(php/:: \DateTimeImmutable ATOM) # <a timestamp>
+```
+
+### Further Reading
+
+This is far from exhaustive, but hopefully it's enough to get you on your feet.
+
+Read the full documentation in the website: [https://phel-lang.org/](https://phel-lang.org/documentation/getting-started/)