kimchilang 1.0.1

package/examples/async_pipe.km

@@ -0,0 +1,58 @@
+// Example: Async pipe (~>) and flow (>>) operators
+// These operators now support async functions seamlessly
+
+// Sync functions work as before
+fn double(x) { return x * 2 }
+fn addOne(x) { return x + 1 }
+fn square(x) { return x * x }
+
+// Async functions - simulate API calls with delays
+async fn fetchUser(id) {
+  // Simulate async operation
+  return { id: id, name: "User" + id }
+}
+
+async fn enrichUser(user) {
+  // Simulate enriching user data
+  return { ...user, email: user.name + "@example.com" }
+}
+
+async fn formatUser(user) {
+  return "Name: " + user.name + ", Email: " + user.email
+}
+
+// Main async function to demonstrate the operators
+async fn main() {
+  print "=== Async Pipe Operator (~>) ==="
+  
+  // Pipe with async functions - each step is awaited
+  dec userInfo = await (1 ~> fetchUser ~> enrichUser ~> formatUser)
+  print userInfo
+  
+  // Mixed sync and async in pipe chain
+  dec result = await (5 ~> double ~> addOne)
+  print "5 ~> double ~> addOne = ${result}"
+  
+  print ""
+  print "=== Async Flow Operator (>>) ==="
+  
+  // Flow creates a reusable async composed function
+  processUser >> fetchUser enrichUser formatUser
+  
+  // Call the composed function - it's async so we await it
+  dec user1 = await processUser(1)
+  dec user2 = await processUser(2)
+  print "User 1: ${user1}"
+  print "User 2: ${user2}"
+  
+  // Flow with sync functions also works
+  transform >> double addOne square
+  dec transformed = await transform(5)
+  print "transform(5) = ${transformed}"
+  
+  print ""
+  print "Done!"
+}
+
+// Run the main function
+main()

package/examples/basic.kimchi

@@ -0,0 +1,109 @@
+// KimchiLang Basic Examples
+// This file demonstrates the core features of KimchiLang
+
+// Variables (all immutable with dec)
+dec name = "World"
+dec PI = 3.14159
+
+// Print statement (convenience syntax)
+print "Hello, KimchiLang!"
+print name
+
+// Functions
+fn greet(person) {
+  return "Hello, " + person + "!"
+}
+
+fn add(a, b) {
+  return a + b
+}
+
+print greet("Alice")
+print add(5, 3)
+
+// Arrow functions
+dec double = x => x * 2
+dec multiply = (a, b) => a * b
+
+print double(21)
+print multiply(6, 7)
+
+// Arrays
+dec numbers = [1, 2, 3, 4, 5]
+dec fruits = ["apple", "banana", "cherry"]
+
+print numbers
+print fruits[0]
+
+// Objects
+dec person = {
+  name: "Bob",
+  age: 30,
+  city: "New York"
+}
+
+print person.name
+print person["age"]
+
+// Control flow - If/Else
+dec score = 85
+
+if score >= 90 {
+  print "Grade: A"
+} elif score >= 80 {
+  print "Grade: B"
+} elif score >= 70 {
+  print "Grade: C"
+} else {
+  print "Grade: F"
+}
+
+// Loops - For (immutable iteration)
+for item in fruits {
+  print item
+}
+
+// Range expressions
+for i in 0..5 {
+  print i
+}
+
+// Flow operator - creates a composed function
+fn addOne(x) {
+  return x + 1
+}
+
+fn square(x) {
+  return x * x
+}
+
+transform >> addOne square
+dec result = transform(5)
+print "transform(5) = ${result}"
+
+// Pipe operator - immediate execution
+dec pipeResult = 5 ~> addOne ~> square
+print "5 ~> addOne ~> square = ${pipeResult}"
+
+// Ternary operator
+dec age = 20
+dec status = age >= 18 ? "adult" : "minor"
+print status
+
+// Spread operator
+dec arr1 = [1, 2, 3]
+dec arr2 = [...arr1, 4, 5, 6]
+print arr2
+
+// Try/Catch
+fn riskyOperation() {
+  throw "Something went wrong!"
+}
+
+try {
+  riskyOperation()
+} catch(e) {
+  print "Caught error: " + e
+}
+
+print "Program completed successfully!"

package/examples/cli_framework/README.md

@@ -0,0 +1,92 @@
+# KimchiLang as a CLI Framework
+
+KimchiLang's built-in module system makes it an excellent choice for building CLI tools. This directory contains examples demonstrating CLI patterns.
+
+## Features for CLI Development
+
+- **`arg` / `!arg`** - Declare optional and required arguments
+- **`_describe()`** - Provide module description for help output
+- **Module paths** - Run modules with `kimchi module.path`
+- **Named args** - Pass `--arg-name value` from command line
+- **Dependency injection** - Mock dependencies for testing
+
+## Examples
+
+### 1. Simple Greeter (`greeter.km`)
+
+A basic CLI tool with required and optional arguments:
+
+```bash
+kimchi cli-framework.greeter --name Alice
+kimchi cli-framework.greeter --name Bob --greeting "Hey there" --times 3
+```
+
+### 2. Calculator (`calculator.km`)
+
+A calculator with multiple operations:
+
+```bash
+kimchi cli-framework.calculator --op add --a 5 --b 3
+kimchi cli-framework.calculator --op multiply --a 7 --b 6
+kimchi cli-framework.calculator --op divide --a 100 --b 4
+```
+
+### 3. Deploy Tool (`deploy.km`)
+
+A deployment tool showing multi-action patterns with environment configuration:
+
+```bash
+kimchi cli-framework.deploy --action build
+kimchi cli-framework.deploy --action test
+kimchi cli-framework.deploy --action publish --target-env production --verbose true
+```
+
+## Running Examples
+
+```bash
+kimchi cli-framework.greeter --name World
+```
+
+## CLI Patterns
+
+### Required vs Optional Arguments
+
+```kimchi
+!arg name        // Required - throws error if missing
+arg greeting     // Optional - undefined if not provided
+```
+
+### Handling Defaults
+
+Since CLI args come as strings, handle defaults explicitly:
+
+```kimchi
+!arg name
+arg greeting
+arg times
+
+dec actualGreeting = greeting ? greeting : "Hello"
+dec actualTimes = times ? Number(times) : 1
+```
+
+### Boolean Flags
+
+Boolean args from CLI come as strings:
+
+```kimchi
+arg verbose
+arg dryRun
+
+dec isVerbose = verbose == "true" || verbose == true
+dec isDryRun = dryRun == "true" || dryRun == true
+```
+
+### Module Description
+
+Provide a `_describe()` function for help output:
+
+```kimchi
+expose fn _describe() {
+  return "A brief description of what this CLI does"
+}
+```

package/examples/cli_framework/calculator.km

@@ -0,0 +1,61 @@
+// Calculator CLI
+// Usage: kimchi cli-framework.calculator --op add --a 5 --b 3
+//        kimchi cli-framework.calculator --op multiply --a 7 --b 6
+
+expose fn _describe() {
+  return "A simple calculator CLI with basic operations"
+}
+
+// Arguments
+!arg op
+!arg a
+!arg b
+
+// Convert string args to numbers
+dec numA = Number(a)
+dec numB = Number(b)
+
+// Operations
+fn doAdd() {
+  dec result = numA + numB
+  print "${numA} + ${numB} = ${result}"
+}
+
+fn doSubtract() {
+  dec result = numA - numB
+  print "${numA} - ${numB} = ${result}"
+}
+
+fn doMultiply() {
+  dec result = numA * numB
+  print "${numA} × ${numB} = ${result}"
+}
+
+fn doDivide() {
+  if numB == 0 {
+    print "Error: Cannot divide by zero"
+    return null
+  }
+  dec result = numA / numB
+  print "${numA} ÷ ${numB} = ${result}"
+}
+
+fn showHelp() {
+  print "Unknown operation: ${op}"
+  print ""
+  print "Available operations:"
+  print "  add      - Add two numbers"
+  print "  subtract - Subtract b from a"
+  print "  multiply - Multiply two numbers"
+  print "  divide   - Divide a by b"
+  print ""
+  print "Example:"
+  print "  kimchi cli-framework.calculator --op add --a 10 --b 5"
+}
+
+// Dispatch
+|op == "add"| => { doAdd() }
+|op == "subtract"| => { doSubtract() }
+|op == "multiply"| => { doMultiply() }
+|op == "divide"| => { doDivide() }
+|true| => { showHelp() }

package/examples/cli_framework/deploy.km

@@ -0,0 +1,126 @@
+// Deploy CLI - Multi-Action Tool
+// Usage: kimchi cli-framework.deploy --action build
+//        kimchi cli-framework.deploy --action test
+//        kimchi cli-framework.deploy --action publish --targetEnv production
+
+expose fn _describe() {
+  return "A deployment tool with multiple actions (build, test, publish)"
+}
+
+// Arguments
+!arg action
+arg targetEnv
+arg verbose
+arg dryRun
+
+// Handle defaults
+dec targetEnvironment = targetEnv ? targetEnv : "development"
+dec isVerbose = verbose == "true" || verbose == true
+dec isDryRun = dryRun == "true" || dryRun == true
+
+// Configuration based on environment
+dec config = {
+  development: {
+    url: "http://localhost:3000",
+    minify: false,
+    sourceMaps: true
+  },
+  staging: {
+    url: "https://staging.example.com",
+    minify: true,
+    sourceMaps: true
+  },
+  production: {
+    url: "https://example.com",
+    minify: true,
+    sourceMaps: false
+  }
+}
+
+dec envConfig = config[targetEnvironment]
+
+// Action handlers
+fn handleBuild() {
+  print "🔨 Building for ${targetEnvironment}..."
+  if isVerbose {
+    print "  Minify: ${envConfig.minify}"
+    print "  Source maps: ${envConfig.sourceMaps}"
+  }
+  
+  if isDryRun {
+    print "  [DRY RUN] Would compile source files"
+    print "  [DRY RUN] Would bundle assets"
+  } else {
+    // Simulate build steps
+    print "  ✓ Compiled source files"
+    print "  ✓ Bundled assets"
+    print "  ✓ Generated output"
+  }
+  
+  print "✅ Build complete!"
+}
+
+fn handleTest() {
+  print "🧪 Running tests..."
+  
+  if isDryRun {
+    print "  [DRY RUN] Would run unit tests"
+    print "  [DRY RUN] Would run integration tests"
+  } else {
+    // Simulate test execution
+    print "  ✓ Unit tests: 42 passed"
+    print "  ✓ Integration tests: 15 passed"
+  }
+  
+  print "✅ All tests passed!"
+}
+
+fn handlePublish() {
+  print "🚀 Publishing to ${targetEnvironment}..."
+  print "  Target: ${envConfig.url}"
+  
+  if targetEnvironment == "production" {
+    print "  ⚠️  WARNING: Publishing to PRODUCTION!"
+  }
+  
+  if isDryRun {
+    print "  [DRY RUN] Would upload build artifacts"
+    print "  [DRY RUN] Would invalidate cache"
+    print "  [DRY RUN] Would notify team"
+  } else {
+    print "  ✓ Uploaded build artifacts"
+    print "  ✓ Invalidated CDN cache"
+    print "  ✓ Notified team via Slack"
+  }
+  
+  print "✅ Published successfully!"
+}
+
+fn showHelp() {
+  print "Unknown action: ${action}"
+  print ""
+  print "Available actions:"
+  print "  build   - Compile and bundle the application"
+  print "  test    - Run the test suite"
+  print "  publish - Deploy to the target environment"
+  print ""
+  print "Examples:"
+  print "  kimchi cli-framework.deploy --action build"
+  print "  kimchi cli-framework.deploy --action publish --target-env production"
+}
+
+// Main dispatch
+print "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+print "  Deploy Tool v1.0"
+print "  Environment: ${targetEnvironment}"
+if isDryRun {
+  print "  Mode: DRY RUN"
+}
+print "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+print ""
+
+// Dispatch action
+|action == "build"| => { handleBuild() }
+|action == "test"| => { handleTest() }
+|action == "publish"| => { handlePublish() }
+|true| => { showHelp() }

package/examples/cli_framework/greeter.km

@@ -0,0 +1,26 @@
+// Simple Greeter CLI
+// Usage: kimchi cli-framework.greeter --name Alice
+//        kimchi cli-framework.greeter --name Bob --greeting "Hey there"
+
+// Module description (shown in `kimchi help`)
+expose fn _describe() {
+  return "A simple greeter CLI tool"
+}
+
+// Arguments
+!arg name
+arg greeting
+arg times
+
+// Main logic
+dec actualGreeting = greeting ? greeting : "Hello"
+dec actualTimes = times ? times : 1
+
+fn greet() {
+  for i in 0..actualTimes {
+    print "${actualGreeting}, ${name}!"
+  }
+}
+
+// Run on module load
+greet()

package/examples/config.static

@@ -0,0 +1,27 @@
+// Example static file with arrays, objects, and enums
+
+Colors [
+  "red"
+  "green"
+  "blue"
+  "yellow"
+]
+
+AppConfig {
+  name = "MyApp"
+  version = "1.0.0"
+  debug = true
+  maxRetries = 3
+  testing = {
+    enabled = true
+    retries = 2
+    timeout = 5000
+  }
+}
+
+HttpStatus `STATUS_OK = 200, STATUS_NOT_FOUND = 404, STATUS_ERROR = 500`
+
+Endpoints {
+  api = "https://api.example.com"
+  auth = "https://auth.example.com"
+}

package/examples/config.static.js

@@ -0,0 +1,10 @@
+// Generated from .static file
+
+export const Colors = ["red", "green", "blue", "yellow"];
+
+export const AppConfig = { name: "MyApp", version: "1.0.0", debug: true, maxRetries: 3 };
+
+export const HttpStatus = Object.freeze({ STATUS_OK: 200, STATUS_NOT_FOUND: 404, STATUS_ERROR: 500 });
+
+export const Endpoints = { api: "https://api.example.com", auth: "https://auth.example.com" };
+

package/examples/env_test.km

@@ -0,0 +1,37 @@
+// Test file for env, arg, and secret keywords
+// Demonstrates: env, !env, arg, secret
+
+// Arguments
+arg name = "World"
+secret arg password = "default-pass"
+
+// Environment variables
+env HOME
+env DEBUG = "false"
+
+// Secret env var - will be masked when printed
+secret env API_TOKEN = "default-token-123"
+
+// Secret dec - will be masked when printed
+secret dec apiKey = "sk-12345-secret-key"
+
+// Normal dec for comparison
+dec normalValue = "visible-value"
+
+print "=== Arguments ==="
+print "Name: ${name}"
+print "Password: ${password}"
+
+print ""
+print "=== Environment Variables ==="
+print "HOME: ${HOME}"
+print "DEBUG: ${DEBUG}"
+
+print ""
+print "=== Secret Values (should be masked) ==="
+print "API Token: ${API_TOKEN}"
+print "API Key: ${apiKey}"
+
+print ""
+print "=== Normal Values (should be visible) ==="
+print "Normal: ${normalValue}"

package/examples/fibonacci.kimchi

@@ -0,0 +1,17 @@
+// Fibonacci sequence in KimchiLang
+
+fn fibonacci(n) {
+  if n <= 1 {
+    return n
+  }
+  return fibonacci(n - 1) + fibonacci(n - 2)
+}
+
+// Print first 10 fibonacci numbers
+print "Fibonacci Sequence:"
+for i in 0..10 {
+  print fibonacci(i)
+}
+
+print "Fibonacci of 15:"
+print fibonacci(15)

package/examples/greeter.km

@@ -0,0 +1,15 @@
+// Simple greeter module
+
+!arg name
+arg greeting = "Hello"
+
+expose fn _describe() {
+  return "A simple greeting module"
+}
+
+expose fn greet() {
+  print "${greeting}, ${name}!"
+}
+
+// Run on load
+greet()

package/examples/hello.js

@@ -0,0 +1 @@
+console.log("Hello, World!");

package/examples/hello.kimchi

@@ -0,0 +1,3 @@
+// Hello World in KimchiLang
+
+print "Hello, World!"

package/examples/js_interop.km

@@ -0,0 +1,42 @@
+// JavaScript Interop Examples
+
+// Simple JS block (no inputs)
+js {
+  console.log("Hello from raw JavaScript!");
+}
+
+// JS block with inputs from kimchi scope
+dec name = "Alice"
+dec count = 5
+
+js(name, count) {
+  const greeting = `Hello, ${name}! Count: ${count}`;
+  console.log(greeting);
+}
+
+// JS block as expression - returns a value
+dec doubled = js(count) {
+  return count * 2;
+}
+print "Doubled: ${doubled}"
+
+// Using JS for complex operations
+dec numbers = [1, 2, 3, 4, 5]
+dec sum = js(numbers) {
+  return numbers.reduce((a, b) => a + b, 0);
+}
+print "Sum: ${sum}"
+
+// Accessing JS libraries
+dec timestamp = js {
+  return Date.now();
+}
+print "Timestamp: ${timestamp}"
+
+// Complex JS with multiple statements
+dec result = js(name) {
+  const upper = name.toUpperCase();
+  const reversed = upper.split('').reverse().join('');
+  return reversed;
+}
+print "Reversed uppercase: ${result}"

package/examples/logger_example.km

@@ -0,0 +1,34 @@
+// Logger Example
+// Demonstrates structured JSON logging with log levels
+
+// Import the logger from stdlib
+as log dep stdlib.logger
+
+// Basic logging at different levels
+log.info("Application started")
+log.debug("Debug information", { userId: 123 })
+log.warn("This is a warning")
+log.error("Something went wrong", { code: "ERR_001" })
+
+// Create a child logger with context
+dec userLog = log.child({ userId: 456, session: "abc123" })
+userLog.info("User logged in")
+userLog.debug("Processing request")
+
+// Function that uses logging
+fn processOrder(orderId) {
+  log.info("Processing order", { orderId: orderId })
+  
+  // Simulate some work
+  log.debug("Validating order")
+  log.debug("Charging payment")
+  
+  log.info("Order completed", { orderId: orderId, status: "success" })
+  return true
+}
+
+processOrder(789)
+
+// To test different log levels, run with:
+// LOG_LEVEL=debug kimchi examples/logger-example.km
+// LOG_LEVEL=warn kimchi examples/logger-example.km

package/examples/memo_fibonacci.km

@@ -0,0 +1,17 @@
+// Memoized Fibonacci - demonstrates the memo keyword
+
+memo fibonacci(n) {
+  if n <= 1 {
+    return n
+  }
+  return fibonacci(n - 1) + fibonacci(n - 2)
+}
+
+// This would be slow without memoization, but with memo it's fast
+print "Memoized Fibonacci Sequence:"
+for i in 0..20 {
+  print "fib(${i}) = ${fibonacci(i)}"
+}
+
+print "\nFibonacci of 35 (would be slow without memo):"
+print "fib(35) = ${fibonacci(35)}"