Community documentation for Janet

# see https://janet-lang.org/docs/abstract_machine.html

(def plus10
 (asm 
   '{
     :arity 1
     :bytecode @[(ldi 1 10)    # $1 = 10
                 (add 2 0 1)   # $2 = $0 + $1
                 (ret 2)]}))   # return $2

(plus10 1) # -> 11

(mod 13 5)  # 3

(def kvpairs [[:x 1] [:y 2]])

(table ;(flatten kvpairs)) # => @{:x 1 :y 2}

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

(def a @[])
(array/push a 1)  # => @[1]
a                 # => @[1]
(array/push a 2)  # => @[1 2]
a                 # => @[1 2]

(doc doc) # works
(doc* doc) # symbol <function doc> not found
(doc* "doc") # same as (doc doc)

(get default-peg-grammar :a)
# => '(range "az" "AZ")

(fiber? (fiber/new (fn [])))
# => true

(merge {:a 1 :b 2} 
       {:c 3 :a 4})
# -> @{:c 3 :a 4 :b 2}

(string/split "\n" @"works\nfor\nbuffers\ntoo")
# => @["works" "for" "buffers" "too"]

(assert :dude :what?) # => :dude

(assert :dude :dude) # => :dude

(assert (= :dude :what?) "Where's my car?")
# => error: Where's my car?
# =>  in _thunk [repl] (tailcall) on line 84, column 1

(assert (= :dude :dude) "Where's my car?") # => true

(if-let [x true 
         y (not x)]
  :a
  :b)
# => :b

(sort (keys default-peg-grammar))
# => @[:A :D :H :S :W :a :a* :a+ :d :d* :d+ :h :h* :h+ :s :s* :s+ :w :w* :w+]

(-> "X"
    (string "a" "b")
    (string "c" "d")
    (string "e" "f"))  # => "Xabcdef"

# 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))