Community documentation for Janet

# To make "stub functions" in an image, solving c interop problems like this:

# I hoped that I would be able to unmarshal the runtime.jimage, load my C functions,
# and Janet would use my app's functions instead of the stubs. However, during
# compilation, Janet seems to precompile all the top-level function calls. This
# means hotswapping the functions does nothing, and the Janet code continues to 
# use the stubs instead.
#
# I was hoping that there would be some way of telling Janet "don't precompile 
# this please", either a (defstubn ...) or the ability to do 
# (defn internal/redraw-ui [opts] (dyn)), where (dyn) is some abstract type that
# Janet can't precompute directly.
# https://github.com/janet-lang/janet/issues/1642


# pretend this is the stub function we want to replace
(defn greet [] (print "hello world"))

# make-image-dict determines which values will be filled in at
# "deserialization" time
(put make-image-dict greet 'greet)
(def pretend-env @{
  'some-function (fn [] (greet) (greet))})

(def compiled (make-image pretend-env))
# notice: the string "hello world" does not appear in the compiled result
(pp compiled)

# if we just try to (load-image compiled) at this point, it will raise,
# because we haven't specified what to do about 'greet

# we have to make an entry in the load-image-dict. note that
# it does not have to be the same value!
(put load-image-dict 'greet (fn [] (print "something else!")))

# now we can call load-image
(def pretend-env-reparsed (load-image compiled))

# and when we run this, we will see the replacement that we gave
((pretend-env-reparsed 'some-function))

(map inc
     (fiber/new |(each x (range 3)
                   (yield x))))
# => @[1 2 3]

(net/address "0.0.0.0" 80) # => <core/socket-address 0x55CABA438E90>

(net/address "0.0.0.0" 8989) # => <core/socket-address 0x55CABA439980>

(defn- parse-timestamp
  ``Parse a date or datetime string into a unix epoch int``
  [s]
  (if (string/find " " s)
    # datetime: "yyyy-MM-dd HH:mm"
    (let [[date-part time-part] (string/split " " s)
          [y m d]               (string/split "-" date-part)
          [hh mm]               (string/split ":" time-part)]
      (os/mktime {:year         (scan-number y)
                  :month        (scan-number m)
                  :month-day    (scan-number d)
                  :hours        (scan-number hh)
                  :minutes      (scan-number mm)
                  :seconds      0}))
    # date: "yyyy-MM-dd"
    (let [[y m d] (string/split "-" s)]
      (os/mktime {:year      (scan-number y)
                  :month     (scan-number m)
                  :month-day (scan-number d)
                  :hours 0 :minutes 0 :seconds 0}))))

(map type [nil true 42 [] @[] {} @{} "a" @"b" 'c :d identity (fn [])])
# => @[:nil :boolean :number :tuple :array :struct :table :string :buffer :symbol :keyword :function :function]

(def a @[1 2])
(array/concat a 3 [4 5] @[6 7] [] @[] 8)
a  # => @[1 2 3 4 5 6 7 8]

(table/clear @{:a 1 :b 2})
# => @{}

# When the :doc-color dynamic binding referenced by *doc-color* is truthy,
# the doc-format function replaces a minimal subset of Markdown markup with
# the corresponding ANSI escape codes.
#
# The following markup is supported:
# - *this will be underlined*
# - **this will be bold**
# - `(+ 1 2 3)` <- backticks for code
#
# You may be surprised by *underline* since the same markup is used to
# indicate italics in Markdown. This is likely a tradeoff for compatibility;
# historically, the italic attribute has not been widely supported by
# terminal emulators.
#
# The best way to see the effect of *doc-color* is try the following examples
# in the Janet REPL.

# By default, *doc-color* is enabled.
(print (doc-format "*underline*. **bold**. `(code)`."))

# Set the dynamic binding to a falsy value to disable doc-format's ANSI
# escape code substition.
(with-dyns [*doc-color* false]
  (print (doc-format "*underline*. **bold**. `(code)`.")))

# N.B.: At the time of writing, no docstrings in the core API take advantage of
# the bold or underline markup As a result, you may not see any difference in
# the doc formatting if your terminal theme uses the same hue for white and
# bright white (a few terminals that I tested on Linux make no distinction
# between the two colors in their default configuration).

(eval-string "(+ 1 2 3 4)") # -> 10
(eval-string ")") # -> parse error
(eval-string "(bloop)") # -> compile error
(eval-string "(+ nil nil)") # -> runtime error

(forever 
 (print "and then?") 
 (ev/sleep 1) 
 (print "no and then!")) 

# => and then? 
# sleeps for one second
# => no and then!
# => and then?
# sleeps for one second
# => no and then!
# ...

(string/replace "+" "-" "ctrl+c")
# => "ctrl-c"

(label result
  (each x [0 1 2 3]
    (when (= x 3)
      (print "reached the end"))
    (when (= x 2)
      (return result 8))))
# => 8

(ev/call print 10)
(ev/sleep 0.0001) # give ev a chance in the REPL, remove in file
# => prints 10

(freeze @{:a @[1 2] 
          :b @{:x @[8 9] 
               :y :smile}})
# => {:a (1 2) :b {:x (8 9) :y :smile}}

(var x 1)
(loop [n :range-to [1 5]]
  (*= x n))
x # => 120