Community documentation for Janet

# *doc-width* is bound to the keyword :doc-width - it can be used in place of
# :doc-width in a call to `dyn`, `setdyn`, or `with-dyns` and is preferable
# to using the keyword directly. When set to a number, it indicates the
# maximum width (in columns) of a row of text returned by `doc-format`.

# - Like *doc-color*, *doc-width* can be used to adjust the output of
#   `doc-format`.
# - When the :doc-width dynamic binding is not set, the default width is 80.
# - By default, `doc-format` adds 4 space indentation and subtracts 8 from
#   the value of the :doc-width dynamic binding to calculate a max width.

# Default:
# repl> (doc doc)
# 
# 
#     macro
#     boot.janet on line 3573, column 1
# 
#     (doc &opt sym)
# 
#     Shows documentation for the given symbol, or can show a list of 
#     available bindings. If sym is a symbol, will look for documentation 
#     for that symbol. If sym is a string or is not provided, will show 
#     all lexical and dynamic bindings in the current environment 
#     containing that string (all bindings will be shown if no string is 
#     given).

# With *doc-width*:
# repl> (with-dyns [*doc-width* 40] (doc doc))
# 
# 
#     macro
#     boot.janet on line 3573, column 1
# 
#     (doc &opt sym)
# 
#     Shows documentation for the 
#     given symbol, or can show a 
#     list of available bindings. 
#     If sym is a symbol, will 
#     look for documentation for 
#     that symbol. If sym is a 
#     string or is not provided, 
#     will show all lexical and 
#     dynamic bindings in the 
#     current environment 
#     containing that string (all 
#     bindings will be shown if 
#     no string is given).

math/e 
# => 2.71828

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

(string/replace-all "e" "o" "feed")
# =>
"food"

(map  |($ {:a 7 :b 8} )   [  keys      values    kvs             pairs                 ])
# =>                     @[  @[:a :b]  @[7 8]    @[:a 7 :b 8]    @[(:a 7) (:b 8)]      ]

(map  |($ [4 5 6] )       [  keys      values    kvs             pairs                 ])
# =>                     @[  @[0 1 2]  @[4 5 6]  @[0 4 1 5 2 6]  @[(0 4) (1 5) (2 6)]  ]

(map  |($ 'ab )           [  keys      values    kvs             pairs                 ])
# =>                     @[  @[0 1]    @[97 98]  @[0 97 1 98]    @[(0 97) (1 98)]      ]

(map  |($ :ab )           [  keys      values    kvs             pairs                 ])
# =>                     @[  @[0 1]    @[97 98]  @[0 97 1 98]    @[(0 97) (1 98)]      ]

(map  |($ "ab" )          [  keys      values    kvs             pairs                 ])
# =>                     @[  @[0 1]    @[97 98]  @[0 97 1 98]    @[(0 97) (1 98)]      ]

(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+]

(last [1 1 2 3 5 8])
# => 8

# Reading a file line by line, using loop's :iterate verb, and adding the line lengths

(with [fl (file/open "filepath")]
  (var sm 0)
  (loop [line :iterate (file/read fl :line)]
    (+= sm (length line)))
   sm) 
 

(comment this is a
         multiline line comment.
         It won't do anything)

# To resume an image's environment:

# With this example image:
# echo "(def a 1)" > test.janet
# janet -c test.janet test.jimage
# Now open the REPL:

# To enter an image, for continued development or exploration. N.b. this does not work as expected:
# See: https://janet.zulipchat.com/#narrow/channel/409517-help/topic/Image.20Based.20Development.3F/with/529177765

(defn restore-image [image]
  (loop [[k v] :pairs image]
    (put (curenv) k v)))

(restore-image (load-image (slurp "test.jimage")))

$ # trivial server which echo's to the console.
$ cat > srv.janet << EOF
#!/usr/bin/env janet

(defn handle-conn [conn]
  (print "new connection")
  (while true
    (def data (net/read conn 4096))
    (if (not data) (break))
    (prin data))
  (net/close conn)
  (print "connection closed"))

(print "starting server on 0.0.0.0:1234")
(net/server "0.0.0.0" 1234 handle-conn)
EOF
$ chmod +x srv.janet
$ ./srv.janet

----

$ # in another terminal:
$ echo hello | nc 0.0.0.0 1234

(def f (ev/spawn 4))
(ev/sleep 0.0001) # give ev a chance in the REPL, remove in file
(fiber/last-value f) # => 4

# due to 0 indexing, you will often want to add 1 to things:
(defn short-date [d]
  (let [{:year y :month mon :month-day d} d]
    (string y "-" (+ 1 mon) "-" (+ 1 d))))

# Makes os/date like 2025-12-25
(short-date (os//date))


# From: https://codeberg.org/veqq/deforester/src/branch/master/deforester.janet
(defn- time-string 
  ``Gives current time as ISO 8601 string: 2025-10-12T11:43:14 https://en.wikipedia.org/wiki/ISO_8601
  This accounts for `os/date` 0-indexing month and days which are 1-indexed in ISO 8601.``
  []
  (let [{:year y :month mon :month-day d :hours h :minutes min :seconds s} (os/date)]
    (string y "-" (+ 1 mon) "-" (+ 1 d) "T" h ":" min ":" s)))

(reduce     + 1 [2 3 4])  # -> 10
(accumulate + 1 [2 3 4])  # -> @[3 6 10]

(def record @{:recipient @{:name "Bob" :age 60} :sender @{:name "Alice" :age 21}})

(put-in
  record
  [:sender :age] 
  26)

# @{:recipient @{:name "Bob" :age 60} :sender @{:name "Alice" :age 26}}

(put-in
  record
  [:recipient] 
  @{:name "Carl"})

# @{:recipient @{:name "Carl"} :sender @{:name "Alice" :age 26}}