arc-lang 0.6.2 → 0.6.4

package/stdlib/README.md

@@ -0,0 +1,64 @@
+# Arc Standard Library
+
+The Arc standard library provides essential modules for common programming tasks, designed with Arc's token-efficiency philosophy.
+
+## Modules
+
+| Module | Status | File | Description |
+|--------|--------|------|-------------|
+| **math** | ✅ Implemented | [`math.arc`](math.arc) | Constants (PI, E) and functions (abs, pow, sqrt, ceil, floor, clamp) |
+| **strings** | ✅ Implemented | [`strings.arc`](strings.arc) | String utilities (pad_left, pad_right, capitalize, words) |
+| **collections** | ✅ Implemented | [`collections.arc`](collections.arc) | List utilities (set, unique, group_by, chunk, flatten, zip_with, partition, sort_by) |
+| **map** | ✅ Implemented | [`map.arc`](map.arc) | Map utilities (merge, map_values, filter_map, from_pairs, pick, omit) |
+| **io** | ✅ Implemented | [`io.arc`](io.arc) | File I/O (read_lines, write_lines, exists, append) |
+| **http** | ✅ Implemented | [`http.arc`](http.arc) | HTTP client (get, post, put, delete, fetch_all, parse_url) |
+| **json** | ✅ Implemented | [`json.arc`](json.arc) | JSON parser/serializer (to_json, from_json, pretty, get_path) |
+| **csv** | ✅ Implemented | [`csv.arc`](csv.arc) | CSV parser/serializer (parse_csv, to_csv, parse_csv_headers) |
+| **test** | ✅ Implemented | [`test.arc`](test.arc) | Testing framework (describe, it, expect_eq, expect_true, run_tests) |
+| **result** | ✅ Implemented | [`result.arc`](result.arc) | Result type (ok, err, is_ok, unwrap, map_result, try_fn) |
+| **time** | ✅ Implemented | [`time.arc`](time.arc) | Time utilities (now, format_duration, sleep) |
+
+## Quick Examples
+
+### math
+
+```arc
+use math
+
+math.sqrt(144)        # => 12
+math.clamp(15, 0, 10) # => 10
+math.PI               # => 3.141592653589793
+```
+
+### strings
+
+```arc
+use strings
+
+strings.pad_left("7", 3, "0")  # => "007"
+strings.capitalize("hello")     # => "Hello"
+strings.words("one two three")  # => ["one", "two", "three"]
+```
+
+## Built-in Functions (No Import)
+
+Many common operations are built into Arc and need no `use` statement:
+
+`print`, `len`, `str`, `int`, `float`, `type`, `split`, `join`, `trim`, `upper`, `lower`, `slice`, `map`, `filter`, `reduce`, `find`, `contains`, `push`, `concat`, `take`, `skip`, `sort`, `reverse`, `keys`, `values`
+
+## Documentation
+
+- **[Standard Library Reference](../docs/stdlib-reference.md)** — Full API reference
+- **[Standard Library Tutorial](../docs/stdlib-tutorial.md)** — Hands-on usage guide
+
+## Design Principles
+
+1. **Minimal but complete** — Cover common use cases without bloat
+2. **Token-efficient** — Short names, clear APIs
+3. **Pipeline-friendly** — Functions work naturally with `|>`
+4. **Well-documented** — Every function has examples
+5. **Consistent** — Similar operations have similar signatures
+
+## Contributing
+
+Help implement the planned modules! See [CONTRIBUTING.md](../CONTRIBUTING.md).

package/stdlib/collections.arc

@@ -0,0 +1,140 @@
+# Arc Standard Library: collections module
+# Advanced collection utilities
+
+pub fn set(list) {
+  let mut result = []
+  for item in list {
+    if not contains(result, item) {
+      result = push(result, item)
+    }
+  }
+  result
+}
+
+pub fn unique(list) => set(list)
+
+pub fn group_by(list, f) {
+  let mut result = {}
+  for item in list {
+    let key = str(f(item))
+    let existing = if contains(keys(result), key) { result[key] } el { [] }
+    result[key] = push(existing, item)
+  }
+  result
+}
+
+pub fn count_by(list, f) {
+  let mut result = {}
+  for item in list {
+    let key = str(f(item))
+    let existing = if contains(keys(result), key) { result[key] } el { 0 }
+    result[key] = existing + 1
+  }
+  result
+}
+
+pub fn chunk(list, size) {
+  if size <= 0 { [] }
+  el if len(list) == 0 { [] }
+  el {
+    let mut result = []
+    let mut i = 0
+    do {
+      let end = if i + size > len(list) { len(list) } el { i + size }
+      result = push(result, slice(list, i, end))
+      i = i + size
+    } until i >= len(list)
+    result
+  }
+}
+
+pub fn flatten(list) => flat(list)
+
+pub fn zip_with(a, b, f) {
+  let mut result = []
+  let pairs = zip(a, b)
+  for p in pairs {
+    result = push(result, f(p[0], p[1]))
+  }
+  result
+}
+
+pub fn partition(list, f) {
+  let passing = filter(list, f)
+  let not_f = x => not f(x)
+  let failing = filter(list, not_f)
+  let result = [passing, failing]
+  result
+}
+
+pub fn frequencies(list) {
+  let mut result = {}
+  for item in list {
+    let key = str(item)
+    let existing = if contains(keys(result), key) { result[key] } el { 0 }
+    result[key] = existing + 1
+  }
+  result
+}
+
+pub fn min_by(list, f) {
+  if len(list) == 0 { nil }
+  el {
+    let mut best = list[0]
+    let mut best_val = f(best)
+    for i in 1..len(list) {
+      let val = f(list[i])
+      if val < best_val {
+        best = list[i]
+        best_val = val
+      }
+    }
+    best
+  }
+}
+
+pub fn max_by(list, f) {
+  if len(list) == 0 { nil }
+  el {
+    let mut best = list[0]
+    let mut best_val = f(best)
+    for i in 1..len(list) {
+      let val = f(list[i])
+      if val > best_val {
+        best = list[i]
+        best_val = val
+      }
+    }
+    best
+  }
+}
+
+pub fn sort_by(list, f) {
+  # Insertion sort by key function
+  let mut arr = map(list, x => x)
+  for i in 1..len(arr) {
+    let mut j = i
+    do {
+      if j <= 0 { j = 0 }
+      el if f(arr[j]) < f(arr[j - 1]) {
+        let tmp = arr[j]
+        arr[j] = arr[j - 1]
+        arr[j - 1] = tmp
+        j = j - 1
+      } el { j = 0 }
+    } until j <= 0
+  }
+  arr
+}
+
+pub fn index_of(list, val) {
+  let mut result = nil
+  for i in 0..len(list) {
+    if list[i] == val and result == nil {
+      result = i
+    }
+  }
+  result
+}
+
+pub fn includes(list, val) => contains(list, val)

package/stdlib/crypto.arc

@@ -0,0 +1,62 @@
+# Arc Standard Library: crypto module
+# Hashing, encryption, and cryptographic utilities
+
+# --- Hashing ---
+
+pub fn md5(text) => crypto_hash("md5", text)
+pub fn sha1(text) => crypto_hash("sha1", text)
+pub fn sha256(text) => crypto_hash("sha256", text)
+pub fn sha512(text) => crypto_hash("sha512", text)
+
+# --- HMAC ---
+
+pub fn hmac_sha256(key, message) => crypto_hmac("sha256", key, message)
+pub fn hmac_sha512(key, message) => crypto_hmac("sha512", key, message)
+
+# --- Random ---
+
+pub fn random_bytes(n) {
+  if n < 0 { panic("random_bytes: n must be non-negative") }
+  el { crypto_random_bytes(n) }
+}
+
+pub fn random_int(min, max) {
+  if min > max { panic("random_int: min must be <= max") }
+  el { crypto_random_int(min, max) }
+}
+
+pub fn uuid() => crypto_uuid()
+
+# --- Base64 ---
+
+pub fn base64_encode(text) => crypto_encode_base64(text)
+pub fn base64_decode(text) => crypto_decode_base64(text)
+
+# --- Password Hashing ---
+
+pub fn hash_password(password, salt) {
+  let input = salt ++ ":" ++ password
+  let mut hash = sha256(input)
+  for i in 0..100 {
+    hash = sha256(hash ++ salt)
+  }
+  hash
+}
+
+pub fn verify_password(password, salt, hash) {
+  let computed = hash_password(password, salt)
+  computed == hash
+}
+
+# --- Utility ---
+
+pub fn constant_time_eq(a, b) {
+  if len(a) != len(b) { false }
+  el {
+    let mut result = true
+    for i in 0..len(a) {
+      if char_at(a, i) != char_at(b, i) { result = false }
+    }
+    result
+  }
+}

package/stdlib/csv.arc

@@ -0,0 +1,40 @@
+# Arc Standard Library: csv module
+# CSV utilities (pure string manipulation)
+
+pub fn parse_csv(text) => __native("csv.parse", text)
+
+pub fn to_csv(rows) {
+  join(map(rows, row => join(map(row, cell => _escape_csv(str(cell))), ",")), "\n")
+}
+
+pub fn parse_csv_headers(text) {
+  let rows = __native("csv.parse", text)
+  if len(rows) < 2 { [] }
+  el {
+    let headers = head(rows)
+    let data_rows = tail(rows)
+    map(data_rows, cells => {
+      let mut row = {}
+      for i in 0..len(headers) {
+        let key = trim(headers[i])
+        let val = if i < len(cells) { cells[i] } el { "" }
+        row[key] = val
+      }
+      row
+    })
+  }
+}
+
+fn _parse_csv_line(line) {
+  # Simple CSV: split by comma, trim each cell
+  let cells = split(line, ",")
+  map(cells, cell => trim(cell))
+}
+
+fn _escape_csv(s) {
+  if contains(s, ",") or contains(s, "\"") or contains(s, "\n") {
+    "\"" ++ replace(s, "\"", "\"\"") ++ "\""
+  } el {
+    s
+  }
+}

package/stdlib/datetime.arc

@@ -0,0 +1,75 @@
+# Arc Standard Library: datetime module
+# Comprehensive date and time utilities
+
+# Constants
+let MS_PER_MINUTE = 60000
+let MS_PER_HOUR = 3600000
+let MS_PER_DAY = 86400000
+
+# Returns the current timestamp in milliseconds since Unix epoch
+pub fn now() => __builtin_now()
+
+# Returns today's date as a map {year, month, day}
+pub fn today() {
+  let ts = now()
+  let days = int(ts / MS_PER_DAY)
+  __builtin_date_from_ts(ts)
+}
+
+# Parse a date string with the given format to a timestamp
+# Format tokens: YYYY, MM, DD, hh, mm, ss
+pub fn parse(date_string, format) => __builtin_date_parse(date_string, format)
+
+# Format a timestamp to a string using the given format
+# Format tokens: YYYY, MM, DD, hh, mm, ss
+pub fn format(timestamp, format_string) => __builtin_date_format(timestamp, format_string)
+
+# Add days to a timestamp, returns new timestamp
+pub fn add_days(timestamp, days) => timestamp + days * MS_PER_DAY
+
+# Add hours to a timestamp, returns new timestamp
+pub fn add_hours(timestamp, hours) => timestamp + hours * MS_PER_HOUR
+
+# Add minutes to a timestamp, returns new timestamp
+pub fn add_minutes(timestamp, minutes) => timestamp + minutes * MS_PER_MINUTE
+
+# Difference in days between two timestamps (absolute value)
+pub fn diff_days(ts1, ts2) {
+  let diff = ts1 - ts2
+  let abs_diff = if diff < 0 { 0 - diff } el { diff }
+  int(abs_diff / MS_PER_DAY)
+}
+
+# Difference in hours between two timestamps (absolute value)
+pub fn diff_hours(ts1, ts2) {
+  let diff = ts1 - ts2
+  let abs_diff = if diff < 0 { 0 - diff } el { diff }
+  int(abs_diff / MS_PER_HOUR)
+}
+
+# Difference in minutes between two timestamps (absolute value)
+pub fn diff_minutes(ts1, ts2) {
+  let diff = ts1 - ts2
+  let abs_diff = if diff < 0 { 0 - diff } el { diff }
+  int(abs_diff / MS_PER_MINUTE)
+}
+
+# Returns the day of the week (0 = Sunday, 6 = Saturday)
+pub fn day_of_week(timestamp) {
+  # Jan 1 1970 was a Thursday (4)
+  let days = int(timestamp / MS_PER_DAY)
+  let result = ((days + 4) % 7 + 7) % 7
+  result
+}
+
+# Returns true if ts1 is before ts2
+pub fn is_before(ts1, ts2) => ts1 < ts2
+
+# Returns true if ts1 is after ts2
+pub fn is_after(ts1, ts2) => ts1 > ts2
+
+# Convert a timestamp to an ISO 8601 string
+pub fn to_iso(timestamp) => __builtin_date_to_iso(timestamp)
+
+# Parse an ISO 8601 string to a timestamp
+pub fn from_iso(iso_string) => __builtin_date_from_iso(iso_string)

package/stdlib/embed.arc

@@ -0,0 +1,42 @@
+# Arc Standard Library: embed module
+# Vector embeddings, similarity search, and text chunking
+
+# --- Vector Math (native implementations for performance) ---
+
+pub fn dot_product(vec_a, vec_b) => embed_dot_product(vec_a, vec_b)
+
+pub fn magnitude(vec) => embed_magnitude(vec)
+
+pub fn cosine_similarity(vec_a, vec_b) => embed_cosine_similarity(vec_a, vec_b)
+
+pub fn normalize(vec) => embed_normalize(vec)
+
+pub fn euclidean_distance(vec_a, vec_b) => embed_euclidean_distance(vec_a, vec_b)
+
+pub fn centroid(vectors) => embed_centroid(vectors)
+
+# --- Similarity Search ---
+
+# Find top_k most similar vectors from candidates list
+# candidates: list of {id, vector} maps
+# Returns: list of {id, score} maps sorted by similarity (descending)
+pub fn most_similar(query_vec, candidates, top_k) => embed_most_similar(query_vec, candidates, top_k)
+
+# --- Text Chunking ---
+
+# Split text into chunks of approximately chunk_size characters
+# Returns list of {chunk, index} maps
+pub fn chunk_and_embed(text, chunk_size) {
+  let mut chunks = []
+  let mut i = 0
+  let text_len = len(text)
+  let mut idx = 0
+  do {
+    let end = if i + chunk_size > text_len { text_len } el { i + chunk_size }
+    let chunk = slice(text, i, end)
+    chunks = push(chunks, {chunk: chunk, index: idx})
+    i = i + chunk_size
+    idx = idx + 1
+  } until i >= text_len
+  chunks
+}

package/stdlib/env.arc

@@ -0,0 +1,10 @@
+# Arc Standard Library: env module
+# Environment variable utilities
+
+pub fn get(key) => __native("env.get", key)
+pub fn get_or(key, default) => __native("env.get_or", key, default)
+pub fn set(key, val) => __native("env.set", key, val)
+pub fn remove(key) => __native("env.remove", key)
+pub fn has(key) => __native("env.has", key)
+pub fn list() => __native("env.list")
+pub fn require(key) => __native("env.require", key)

package/stdlib/error.arc

@@ -0,0 +1,36 @@
+# Arc Standard Library: error module
+# Structured error handling
+
+# Create a structured error
+pub fn error(code, message) => error_new(code, message)
+
+# Check if a value is an error
+pub fn is_error(value) => error_is_error(value)
+
+# Wrap an error with additional context
+pub fn wrap_error(err, context) => error_wrap(err, context)
+
+# Try executing a function, return Ok/Err result
+pub fn try_fn(f) => error_try(f)
+
+# Execute fn, call handler if result is an error
+pub fn try_catch(f, handler) {
+  let result = f()
+  if is_error(result) { handler(result) }
+  el { result }
+}
+
+# Execute fn, always run cleanup
+pub fn try_finally(f, cleanup) {
+  let result = f()
+  cleanup()
+  result
+}
+
+# Full try/catch/finally
+pub fn try_catch_finally(f, handler, cleanup) {
+  let result = f()
+  let handled = if is_error(result) { handler(result) } el { result }
+  cleanup()
+  handled
+}

package/stdlib/html.arc

@@ -0,0 +1,30 @@
+# Arc Standard Library: html module
+# HTML parsing and generation utilities
+
+pub fn parse(s) {
+  __native("html.parse", s)
+}
+
+pub fn select(node, selector) {
+  __native("html.select", node, selector)
+}
+
+pub fn text(node) {
+  __native("html.text", node)
+}
+
+pub fn attr(node, name) {
+  __native("html.attr", node, name)
+}
+
+pub fn create(tag, attrs, children) {
+  let node = {}
+  node["tag"] = tag
+  node["attrs"] = attrs
+  node["children"] = children
+  node
+}
+
+pub fn render(node) {
+  __native("html.render", node)
+}

package/stdlib/http.arc

@@ -0,0 +1,43 @@
+# Arc Standard Library: http module
+# HTTP utilities built on @ tool calls
+
+pub fn get(url) => @GET url
+
+pub fn post(url, body) {
+  @POST url {data: body}
+}
+
+pub fn put(url, body) {
+  @PUT url {data: body}
+}
+
+pub fn delete(url) => @DELETE url
+
+pub fn fetch_all(urls) {
+  map(urls, u => @GET u)
+}
+
+pub fn parse_url(url) {
+  # Extract protocol, host, path from URL string
+  let mut protocol = ""
+  let mut rest = url
+
+  if starts(url, "https://") {
+    protocol = "https"
+    rest = slice(url, 8, len(url))
+  } el if starts(url, "http://") {
+    protocol = "http"
+    rest = slice(url, 7, len(url))
+  } el {
+    protocol = ""
+    rest = url
+  }
+
+  # Find first / after protocol
+  let parts = split(rest, "/")
+  let host = head(parts)
+  let path_parts = tail(parts)
+  let path = if len(path_parts) > 0 { "/" ++ join(path_parts, "/") } el { "/" }
+
+  {protocol: protocol, host: host, path: path}
+}

package/stdlib/io.arc

@@ -0,0 +1,28 @@
+# Arc Standard Library: io module
+# File I/O utilities (operates on strings/lists; actual I/O via prelude read/write)
+
+pub fn read_lines(path) {
+  let content = read(path)
+  if content == nil { [] }
+  el { split(content, "\n") }
+}
+
+pub fn write_lines(path, lines) {
+  let content = join(lines, "\n")
+  write(path, content)
+}
+
+pub fn exists(path) {
+  # Simulated: try reading, return true if non-nil
+  let content = read(path)
+  content != nil
+}
+
+pub fn append(path, data) {
+  let existing = read(path)
+  if existing == nil {
+    write(path, str(data))
+  } el {
+    write(path, existing ++ str(data))
+  }
+}