(ns Kernel
  "Elixir Kernel module — core functions auto-imported into every module.

   In CljElixir: most Kernel functions are available as builtins (e.g., +, -, if, etc.).
   Use (Kernel/function ...) for less common ones.
   Note: many of these are already available as CljElixir builtins without the Kernel/ prefix.")

;; --- Type Checking ---

(defn is-atom
  "Returns true if `term` is an atom.
   (Kernel/is-atom :hello) ;=> true"
  [term])

(defn is-binary
  "Returns true if `term` is a binary (string).
   (Kernel/is-binary \"hello\") ;=> true"
  [term])

(defn is-bitstring
  "Returns true if `term` is a bitstring."
  [term])

(defn is-boolean
  "Returns true if `term` is a boolean.
   (Kernel/is-boolean true) ;=> true"
  [term])

(defn is-float
  "Returns true if `term` is a float.
   (Kernel/is-float 1.0) ;=> true"
  [term])

(defn is-function
  "Returns true if `term` is a function, optionally with given `arity`.
   (Kernel/is-function f) ;=> true
   (Kernel/is-function f 2) ;=> true if f accepts 2 args"
  ([term])
  ([term arity]))

(defn is-integer
  "Returns true if `term` is an integer.
   (Kernel/is-integer 42) ;=> true"
  [term])

(defn is-list
  "Returns true if `term` is a list.
   (Kernel/is-list [1 2 3]) ;=> true"
  [term])

(defn is-map
  "Returns true if `term` is a map.
   (Kernel/is-map {:a 1}) ;=> true"
  [term])

(defn is-map-key
  "Returns true if `key` exists in `map`. Allowed in guard expressions."
  [map key])

(defn is-nil
  "Returns true if `term` is nil.
   (Kernel/is-nil nil) ;=> true"
  [term])

(defn is-number
  "Returns true if `term` is a number (integer or float).
   (Kernel/is-number 42) ;=> true"
  [term])

(defn is-pid
  "Returns true if `term` is a PID.
   (Kernel/is-pid (Process/self)) ;=> true"
  [term])

(defn is-port
  "Returns true if `term` is a port."
  [term])

(defn is-reference
  "Returns true if `term` is a reference."
  [term])

(defn is-tuple
  "Returns true if `term` is a tuple.
   (Kernel/is-tuple #el[1 2 3]) ;=> true"
  [term])

(defn is-struct
  "Returns true if `term` is a struct.
   (Kernel/is-struct term)
   (Kernel/is-struct term MyStruct) ;=> checks specific struct type"
  ([term])
  ([term name]))

(defn is-exception
  "Returns true if `term` is an exception."
  ([term])
  ([term name]))

;; --- Arithmetic (also available as +, -, *, / builtins) ---

(defn div
  "Integer division (truncated).
   (Kernel/div 10 3) ;=> 3"
  [dividend divisor])

(defn rem
  "Integer remainder (same sign as dividend).
   (Kernel/rem 10 3) ;=> 1"
  [dividend divisor])

(defn abs
  "Returns the absolute value.
   (Kernel/abs -5) ;=> 5"
  [number])

(defn max
  "Returns the maximum of two terms.
   (Kernel/max 1 2) ;=> 2"
  [first second])

(defn min
  "Returns the minimum of two terms.
   (Kernel/min 1 2) ;=> 1"
  [first second])

(defn ceil
  "Returns the smallest integer >= number.
   (Kernel/ceil 1.2) ;=> 2"
  [number])

(defn floor
  "Returns the largest integer <= number.
   (Kernel/floor 1.8) ;=> 1"
  [number])

(defn round
  "Rounds to the nearest integer.
   (Kernel/round 1.5) ;=> 2"
  [number])

(defn trunc
  "Truncates the float to an integer.
   (Kernel/trunc 1.9) ;=> 1"
  [number])

;; --- Comparison ---

(defn ==
  "Structural equality. 1 == 1.0 is true.
   (Kernel/== 1 1.0) ;=> true"
  [left right])

(defn ===
  "Strict equality. 1 === 1.0 is false.
   (Kernel/=== 1 1.0) ;=> false"
  [left right])

(defn !=
  "Not equal (structural).
   (Kernel/!= 1 2) ;=> true"
  [left right])

(defn !==
  "Strict not equal.
   (Kernel/!== 1 1.0) ;=> true"
  [left right])

;; --- String & Binary ---

(defn to-string
  "Converts `term` to a string via the String.Chars protocol.
   (Kernel/to-string 123) ;=> \"123\"
   (Kernel/to-string :hello) ;=> \"hello\""
  [term])

(defn inspect
  "Returns a string representation of `term` (via Inspect protocol).
   (Kernel/inspect {:a 1}) ;=> \"%{a: 1}\""
  ([term])
  ([term opts]))

(defn byte-size
  "Returns the number of bytes in a binary.
   (Kernel/byte-size \"hello\") ;=> 5"
  [binary])

(defn bit-size
  "Returns the number of bits in a bitstring."
  [bitstring])

(defn binary-part
  "Extracts a binary part.
   (Kernel/binary-part \"hello\" 1 3) ;=> \"ell\""
  ([binary start length]))

;; --- Process & Node ---

(defn self
  "Returns the PID of the calling process.
   (Kernel/self) ;=> #PID<0.123.0>"
  [])

(defn node
  "Returns the current node name, or the node for a given PID/ref.
   (Kernel/node) ;=> :nonode@nohost"
  ([])
  ([pid-or-ref]))

(defn spawn
  "Spawns a new process. Returns PID.
   (Kernel/spawn (fn [] (IO/puts \"hello\")))"
  ([fun])
  ([module fun args]))

(defn spawn-link
  "Spawns a linked process.
   (Kernel/spawn-link (fn [] (IO/puts \"linked\")))"
  ([fun])
  ([module fun args]))

(defn spawn-monitor
  "Spawns a monitored process. Returns {pid ref}."
  ([fun])
  ([module fun args]))

(defn send
  "Sends a message. Returns the message.
   (Kernel/send pid :hello)"
  [dest msg])

(defn exit
  "Sends an exit signal.
   (Kernel/exit :normal)"
  [reason])

;; --- Tuple Operations ---

(defn elem
  "Gets element at `index` from a tuple (0-based).
   (Kernel/elem #el[:a :b :c] 1) ;=> :b"
  [tuple index])

(defn put-elem
  "Puts `value` at `index` in a tuple.
   (Kernel/put-elem #el[:a :b :c] 1 :x) ;=> #el[:a :x :c]"
  [tuple index value])

(defn tuple-size
  "Returns the number of elements in a tuple.
   (Kernel/tuple-size #el[1 2 3]) ;=> 3"
  [tuple])

(defn make-ref
  "Creates a unique reference.
   (Kernel/make-ref) ;=> #Reference<0.0.0.1>"
  [])

;; --- List Operations ---

(defn hd
  "Returns the head of a list.
   (Kernel/hd [1 2 3]) ;=> 1"
  [list])

(defn tl
  "Returns the tail of a list.
   (Kernel/tl [1 2 3]) ;=> [2 3]"
  [list])

(defn length
  "Returns the length of a list.
   (Kernel/length [1 2 3]) ;=> 3"
  [list])

(defn in
  "Membership test (for use in guards). Checks if `elem` is in `list`.
   (Kernel/in x [1 2 3])"
  [elem list])

;; --- Misc ---

(defn apply
  "Applies `fun` with `args`.
   (Kernel/apply Enum :map [[1 2 3] inc])"
  ([fun args])
  ([module fun args]))

(defn function-exported?
  "Returns true if `module` exports `function` with given `arity`.
   (Kernel/function-exported? Enum :map 2) ;=> true"
  [module function arity])

(defn struct
  "Creates a struct from a module.
   (Kernel/struct MyStruct {:field \"value\"})"
  ([module])
  ([module fields]))

(defn struct!
  "Like struct/2 but raises on invalid keys."
  ([module])
  ([module fields]))

(defn raise
  "Raises a RuntimeError or specific exception.
   (Kernel/raise \"something went wrong\")
   (Kernel/raise ArgumentError :message \"bad arg\")"
  ([message])
  ([exception attrs]))

(defn reraise
  "Re-raises an exception preserving the original stacktrace."
  ([message stacktrace])
  ([exception attrs stacktrace]))

(defn throw
  "Throws a value to be caught with try/catch.
   (Kernel/throw :some-value)"
  [value])

(defn tap
  "Pipes `value` into `fun` for side effects, returns `value`.
   (Kernel/tap {:a 1} (fn [x] (IO/inspect x))) ;=> {:a 1}"
  [value fun])

(defn then
  "Pipes `value` into `fun`, returns the result of `fun`.
   (Kernel/then 5 (fn [x] (* x 2))) ;=> 10"
  [value fun])

(defn dbg
  "Debug macro. Prints the code and its result. Returns the result.
   (Kernel/dbg (+ 1 2)) ;=> prints '(+ 1 2) #=> 3', returns 3"
  ([code])
  ([code opts]))