simple_env

Getting Started

Installation

1. Set the environment variable:

   export SIMPLE_EIFFEL=/d/prod

2. Add to your ECF file:

   <library name="simple_env" location="$SIMPLE_EIFFEL/simple_env/simple_env.ecf"/>

Basic Usage

local
    env: SIMPLE_ENV
do
    create env

    -- Get a variable
    if attached env.get ("PATH") as path then
        print ("PATH = " + path)
    end

    -- Set a variable
    env.set ("MY_VAR", "my_value")

    -- Check existence
    if env.has ("MY_VAR") then
        print ("Variable exists!")
    end
end

Getting Environment Variables

Using get

The get feature returns a detachable STRING_32. If the variable doesn't exist, it returns Void.

local
    env: SIMPLE_ENV
do
    create env

    -- Using attached pattern (recommended)
    if attached env.get ("USERPROFILE") as profile then
        print ("User profile: " + profile)
    else
        print ("USERPROFILE not set")
    end
end

Array-Style Access

Use bracket notation for cleaner code:

local
    env: SIMPLE_ENV
do
    create env

    -- Array-style access
    if attached env ["PATH"] as path then
        print (path)
    end

    -- Multiple variables
    if attached env ["TEMP"] as temp then
        print ("Temp dir: " + temp)
    end
end

Checking Existence

Use has to check if a variable exists without getting its value:

if env.has ("DEBUG") then
    enable_debug_mode
end

-- Different from checking empty string!
-- A variable can exist with an empty value

Setting Environment Variables

Basic Setting

local
    env: SIMPLE_ENV
do
    create env

    -- Set a variable
    env.set ("APP_MODE", "production")

    -- Check if it succeeded
    if env.last_operation_succeeded then
        print ("Variable set successfully")
    else
        print ("Failed to set variable")
    end
end

Alternative Syntax (HASH_TABLE Convention)

The put feature follows the HASH_TABLE convention with swapped arguments:

-- set (name, value) - natural order
env.set ("NAME", "value")

-- put (value, name) - HASH_TABLE convention
env.put ("value", "NAME")

Unsetting Variables

-- Remove a variable
env.unset ("TEMP_VAR")

if env.last_operation_succeeded then
    print ("Variable removed")
end

-- Verify it's gone
if not env.has ("TEMP_VAR") then
    print ("Confirmed: variable no longer exists")
end

String Expansion

Expanding %VAR% References

The expand feature resolves Windows-style %VAR% references:

local
    env: SIMPLE_ENV
    expanded: STRING_32
do
    create env

    -- Expand single variable
    expanded := env.expand ("%USERPROFILE%")
    -- Result: "C:\Users\John"

    -- Expand within path
    expanded := env.expand ("%USERPROFILE%\Documents")
    -- Result: "C:\Users\John\Documents"

    -- Multiple variables
    expanded := env.expand ("%SYSTEMROOT%\System32\%USERNAME%")

    -- Unknown variables are left as-is
    expanded := env.expand ("%UNKNOWN%")
    -- Result: "%UNKNOWN%"
end

Building Dynamic Paths

local
    config_path: STRING_32
do
    -- Build configuration path
    config_path := env.expand ("%APPDATA%\MyApp\config.json")

    -- Build temp file path
    temp_path := env.expand ("%TEMP%\myapp_" + timestamp + ".tmp")

    -- Build log path with date
    log_path := env.expand ("%PROGRAMDATA%\MyApp\Logs\") + date_string + ".log"
end

Enumerating Variables

Getting All Variable Names

local
    env: SIMPLE_ENV
    all_names: ARRAYED_LIST [STRING_32]
do
    create env

    -- Get all environment variable names
    all_names := env.all_names

    print ("Total variables: " + all_names.count.out + "%N")

    -- List them all
    across all_names as name loop
        print (name + "%N")
    end
end

Filtering by Prefix

local
    env: SIMPLE_ENV
    app_vars: ARRAYED_LIST [STRING_32]
do
    create env

    -- Get all variables starting with "APP_"
    app_vars := env.names_with_prefix ("APP_")

    across app_vars as name loop
        if attached env.get (name) as value then
            print (name + " = " + value + "%N")
        end
    end

    -- Find all SIMPLE_* library paths
    across env.names_with_prefix ("SIMPLE_") as lib loop
        print (lib + "%N")
    end
end

Error Handling

Checking Operation Status

local
    env: SIMPLE_ENV
do
    create env

    -- Set a variable
    env.set ("CONFIG", "/path/to/config")

    if not env.last_operation_succeeded then
        -- Handle failure
        print ("Failed to set environment variable")
        -- Possible causes: insufficient permissions, system limit reached
    end

    -- Unset a variable
    env.unset ("OLD_CONFIG")

    if not env.last_operation_succeeded then
        -- Variable may not have existed, or permission denied
    end
end

Safe Access Pattern

local
    database_url: STRING_32
do
    -- Get with default fallback
    if attached env.get ("DATABASE_URL") as url then
        database_url := url
    else
        database_url := "localhost:5432"  -- default
    end
end

Common Windows Variables

Reference for commonly-used Windows environment variables:

SCOOP Compatibility

simple_env is designed for use with SCOOP (Simple Concurrent Object-Oriented Programming):

local
    env: separate SIMPLE_ENV
do
    create env

    -- Access through separate handler
    read_config (env)
end

read_config (a_env: separate SIMPLE_ENV)
    local
        config_value: STRING_32
    do
        if attached a_env.get ("CONFIG") as v then
            config_value := v.twin  -- Copy to local
        end
    end

Key points for SCOOP usage:

• Each instance operates independently
• No shared mutable state between instances
• Direct Win32 API calls are atomic
• String results should be copied when needed across separate boundaries