(ns IO
  "Elixir IO module — input/output operations.

   In CljElixir: (IO/puts msg), (IO/inspect val), etc.
   Handles reading/writing to stdio, files, and IO devices.")

(defn puts
  "Writes `item` to the device followed by a newline. Returns :ok.
   (IO/puts \"hello\") ;=> prints 'hello\\n', returns :ok
   (IO/puts :stderr \"error!\") ;=> prints to stderr"
  ([item])
  ([device item]))

(defn write
  "Writes `item` to the device without a trailing newline.
   (IO/write \"hello\") ;=> prints 'hello', returns :ok"
  ([item])
  ([device item]))

(defn inspect
  "Inspects the given value and prints it. Returns the value (pass-through).
   (IO/inspect {:a 1}) ;=> prints '%{a: 1}', returns {:a 1}
   (IO/inspect val :label \"debug\") ;=> prints 'debug: ...'
   Useful for debugging — can be inserted anywhere in a pipeline."
  ([item])
  ([item opts])
  ([device item opts]))

(defn gets
  "Reads a line from the IO device. Shows `prompt` and returns user input.
   (IO/gets \"Enter name: \") ;=> \"Alice\\n\""
  ([prompt])
  ([device prompt]))

(defn read
  "Reads from the IO device.
   (IO/read :stdio :line) ;=> reads one line
   (IO/read :stdio 10) ;=> reads 10 characters"
  ([device count-or-line])
  ([device count-or-line opts]))

(defn warn
  "Writes `message` to stderr followed by a newline.
   (IO/warn \"deprecation warning\")"
  [message])

(defn iodata-to-binary
  "Converts iodata (a list of binaries/integers/iolists) to a single binary.
   (IO/iodata-to-binary [\"hello\" \" \" \"world\"]) ;=> \"hello world\""
  [iodata])

(defn iodata-length
  "Returns the length of iodata without converting to binary.
   (IO/iodata-length [\"hello\" \" \" \"world\"]) ;=> 11"
  [iodata])

(defn chardata-to-string
  "Converts chardata to a string."
  [chardata])

(defn getn
  "Gets a number of bytes from IO device.
   (IO/getn \"prompt> \" 3)"
  ([prompt])
  ([prompt count])
  ([device prompt count]))

(defn binread
  "Reads `count` bytes from IO device as binary.
   (IO/binread :stdio 10)"
  ([device count])
  ([count]))

(defn binwrite
  "Writes binary data to IO device.
   (IO/binwrite :stdio <<1 2 3>>)"
  ([device iodata])
  ([iodata]))

(defn stream
  "Converts an IO device into a Stream. Useful for lazy line-by-line reading.
   (IO/stream :stdio :line)"
  ([device mode]))