Community documentation for Janet

(any? [false false nil]) => nil
(any? [false false nil 1]) => 1
(any? [false false nil true]) => true

(os/execute
  ["/usr/bin/bash" "-c" "set"]
  :e
  @{"SOME" "value"
    "OTHER" "one"})
# => 0

# execute bash and prints environment variables
# which contains SOME=value and Other=one

(os/realpath ".") # => "/home/jgarte"

(os/realpath "Downloads") # => "/home/jgarte/Downloads"

(invert :yo)
# => @{111 1 121 0}

(string/repeat "moshi" 2)  # => "moshimoshi"

(array/pop (range 12)) # => 11

(next  [4 5 6]    )  # => 0
(next  [4 5 6]  0 )  # => 1
(next  [4 5 6]  1 )  # => 2
(next  [4 5 6]  2 )  # => nil

# note that dictionary keys are not necessarily in the same order
# as the corresponding literal.
(next  {:a 5 :b 6 :c 7}     )  # => :a
(next  {:a 5 :b 6 :c 7}  :a )  # => :c
(next  {:a 5 :b 6 :c 7}  :c )  # => :b
(next  {:a 5 :b 6 :c 7}  :b )  # => nil

(def a @[1 2 3])
(array/fill a 17)   # => @[17 17 17]
(array/fill a "n")  # => @["b" "b" "b"]
(array/fill a)      # => @[nil nil nil]
a                   # => @[nil nil nil]

# Consider this problem: As a module author, I want to define a dynamic
# binding `:debug` to provide additional diagnostic information when an
# error occurs in a module function. I'll use `defdyn` to create a public
# alias for my dynamic binding:

# In the file: my-mod.janet
# The `defdyn` macro creates the dynamic binding :debug, and explicitly
# exposes it in the module's API as `my-mod/*debug*`.
(defdyn *debug*)

# contrived function - the important thing is that it enables additional
# diagnostic logging when the `*debug*` alias's reference dynamic binding
# is true.
(defn my-func [& params]
  (try
    (do
      (when (empty? params)
        (error "missing required argument")))
    ([err fib]
      (when (dyn *debug*)
        (print "[diagnostics] ..."))
      (error (string "error occurred: " err)))))

# Let's test our module from the REPL.

# $ repl:1:> (import /my-mod)
# $ repl:2:> (setdyn my-mod/*debug* true) # enable debug mode
# $ repl:3:> (my-mod/my-func)
# [diagnostics] ...
# error: error occured: missing required argument
#   in my-func [my-mod.janet] on line 11, column 7
#   in thunk [repl] (tail call) on line 4, column 1
# entering debug[1] - (quit) to exit
# debug[1]:1:>

# We see our diagnostic message, but we also entered Janet's built-in
# debugger! That's not what we intended. Why did this happen?

# It turns out that our module's `my-mod/*debug*` alias is namespaced, but the
# referenced `:debug` dynamic binding is not. We've created a collision with
# the `:debug` dynamic binding in the core API that activates the debugger
# on error.

# $ repl> *debug*
:debug
# $ repl> my-mod/*debug*
:debug

# The solution is to set the :defdyn-prefix dynamic binding to add a namespace
# for all dynamic bindings in our module. We should use a reasonably unique
# prefix - let's go with the name of the module's public git repo. It's okay
# for the prefix to be long - it will be used as the key for the dynamic
# binding in the current environment, but the user won't typically interact
# with it directly. The prefix is effectively "hidden" from the user. We'll
# prepend this line at the top of our module:
(setdyn *defdyn-prefix* "codeberg.org/quexxon/my-mod/")

# Now our `my-mod/*debug*` alias refers to an isolated, namespaced binding:
# $ repl:1:> (import /my-mod)
# $ repl:2:> my-mod/*debug*
:codeberg.org/quexxon/my-mod/debug
# $ repl:3:> (setdyn my-mod/*debug* true) # enable debug mode
# $ repl:4:> (my-mod/my-func)
# [diagnostics] ...
# error: error occured: missing required argument
#   in my-func [my-mod.janet] on line 11, column 7
#   in thunk [repl] (tail call) on line 4, column 1
# $ repl:5:>

# Much better! We see our diagnostic message, but we didn't trigger Janet's
# debugger. As a general rule, always set `*defdyn-prefix*` to a unique
# value when defining dynamic bindings for your module.

(-> @{:a 0 :b 0}
    (update :a inc)
    (update :b inc))
# => @{:a 1 :b 1}

(get (os/environ) "HOME")  # => "/Users/cell"
(os/getenv "HOME")  # => "/Users/cell"

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

(peg/find-all ':d "hi 1 bye 2") # => @[3 9]

(type print)
# =>
:cfunction

(+ 1 2 3)      # => 6
(sum [1 2 3])  # => 6

(map dictionary? [ 'ab   :ab   "ab"   @"ab"  [97 98]  @[97 98]  {0 97 1 98}  @{0 97 1 98}  ])
# =>            @[ false false false  false  false    false     true         true          ]

(map struct?     [ 'ab   :ab   "ab"   @"ab"  [97 98]  @[97 98]  {0 97 1 98}  @{0 97 1 98}  ])
# =>            @[ false false false  false  false    false     true         false         ]

(map table?      [ 'ab   :ab   "ab"   @"ab"  [97 98]  @[97 98]  {0 97 1 98}  @{0 97 1 98}  ])
# =>            @[ false false false  false  false    false     false        true          ]

# :when modifier argument example

(let [even-numbers  @[]]
    (loop [i :range [0 50] :when (even? i)]
        (array/push even-numbers i))
    even-numbers)

# => @[0 2 4 6 8 10 12 14 16 1.....]

(math/log (* math/e math/e))  # => 2
(math/log2 256)               # => 8
(math/log10 1000)             # => 3

(janet/version 0) # => 49

(janet/version 1) # => 46

(janet/version 2) # => 49

(janet/version 3) # => 55

(janet/version 4) # => 46

(janet/version 5) # => 50

(empty? {})
# => true