☕ @ Operator Introduction in TuskLang - Java Edition

Java Documentation

@ Operator Introduction in TuskLang - Java Edition

"We don't bow to any king" - @ Operator Power with Java Integration

The @ operator is the heart of TuskLang's dynamic configuration system. It provides access to environment variables, database queries, HTTP requests, and much more. The Java SDK offers robust @ operator integration with type safety and validation.

🎯 Java @ Operator Integration

@TuskConfig @ Operator Support

import org.tusklang.java.config.TuskConfig;
import org.tusklang.java.operators.AtOperator;
import org.tusklang.java.operators.EnvironmentOperator;
import org.tusklang.java.operators.DatabaseOperator;
import org.tusklang.java.operators.HttpOperator;
import org.tusklang.java.annotations.TuskOperator;

@TuskConfig public class AtOperatorConfig { // Environment variable operators @TuskOperator("@env") private String databaseHost; @TuskOperator("@env.secure") private String databasePassword; @TuskOperator("@env.default") private int serverPort; // Database query operators @TuskOperator("@query") private Integer userCount; @TuskOperator("@query.param") private String recentUser; // HTTP request operators @TuskOperator("@http.get") private String apiResponse; @TuskOperator("@http.post") private String apiData; // Date and time operators @TuskOperator("@date.now") private String currentTime; @TuskOperator("@date.format") private String formattedDate; // Cache operators @TuskOperator("@cache") private String cachedValue; @TuskOperator("@cache.ttl") private String cachedWithTtl; // Metrics operators @TuskOperator("@metrics") private Double responseTime; // Machine learning operators @TuskOperator("@learn") private String optimizedValue; @TuskOperator("@optimize") private Double optimizedSetting; // File operators @TuskOperator("@file.read") private String fileContent; @TuskOperator("@file.write") private boolean fileWritten; // JSON operators @TuskOperator("@json.parse") private Map<String, Object> parsedJson; @TuskOperator("@json.stringify") private String jsonString; // Validation operators @TuskOperator("@validate") private boolean isValid; @TuskOperator("@validate.email") private boolean isEmailValid; // Encryption operators @TuskOperator("@encrypt") private String encryptedData; @TuskOperator("@decrypt") private String decryptedData; // Operator context and configuration private AtOperatorContext operatorContext; public AtOperatorConfig() { this.operatorContext = new AtOperatorContext(); initializeOperators(); } // Initialize @ operators with Java integration private void initializeOperators() { // Environment operator EnvironmentOperator envOp = new EnvironmentOperator(); envOp.setSecureMode(true); envOp.setDefaultProvider(System::getenv); // Database operator DatabaseOperator dbOp = new DatabaseOperator(); dbOp.setConnectionPool(createConnectionPool()); dbOp.setQueryTimeout(30); // HTTP operator HttpOperator httpOp = new HttpOperator(); httpOp.setTimeout(5000); httpOp.setRetryAttempts(3); // Register operators operatorContext.registerOperator("env", envOp); operatorContext.registerOperator("query", dbOp); operatorContext.registerOperator("http", httpOp); } // Create database connection pool private DataSource createConnectionPool() { HikariConfig config = new HikariConfig(); config.setJdbcUrl("jdbc:postgresql://localhost:5432/tuskdb"); config.setUsername("postgres"); config.setPassword("password"); config.setMaximumPoolSize(10); return new HikariDataSource(config); } // Execute @ operator with Java integration public Object executeAtOperator(String operator, String... parameters) { try { return operatorContext.execute(operator, parameters); } catch (Exception e) { throw new AtOperatorException("Failed to execute @ operator: " + operator, e); } } // Validate @ operator configuration public boolean validateAtOperators() { List<String> errors = new ArrayList<>(); // Validate environment variables if (databaseHost == null || databaseHost.isEmpty()) { errors.add("Database host environment variable not set"); } // Validate database connection if (userCount == null) { errors.add("Database query failed for user count"); } // Validate HTTP endpoints if (apiResponse == null) { errors.add("HTTP GET request failed"); } if (!errors.isEmpty()) { throw new AtOperatorException("@ operator validation failed: " + String.join(", ", errors)); } return true; } // Getters and setters public String getDatabaseHost() { return databaseHost; } public void setDatabaseHost(String databaseHost) { this.databaseHost = databaseHost; } public String getDatabasePassword() { return databasePassword; } public void setDatabasePassword(String databasePassword) { this.databasePassword = databasePassword; } public int getServerPort() { return serverPort; } public void setServerPort(int serverPort) { this.serverPort = serverPort; } public Integer getUserCount() { return userCount; } public void setUserCount(Integer userCount) { this.userCount = userCount; } public String getRecentUser() { return recentUser; } public void setRecentUser(String recentUser) { this.recentUser = recentUser; } public String getApiResponse() { return apiResponse; } public void setApiResponse(String apiResponse) { this.apiResponse = apiResponse; } public String getApiData() { return apiData; } public void setApiData(String apiData) { this.apiData = apiData; } public String getCurrentTime() { return currentTime; } public void setCurrentTime(String currentTime) { this.currentTime = currentTime; } public String getFormattedDate() { return formattedDate; } public void setFormattedDate(String formattedDate) { this.formattedDate = formattedDate; } public String getCachedValue() { return cachedValue; } public void setCachedValue(String cachedValue) { this.cachedValue = cachedValue; } public String getCachedWithTtl() { return cachedWithTtl; } public void setCachedWithTtl(String cachedWithTtl) { this.cachedWithTtl = cachedWithTtl; } public Double getResponseTime() { return responseTime; } public void setResponseTime(Double responseTime) { this.responseTime = responseTime; } public String getOptimizedValue() { return optimizedValue; } public void setOptimizedValue(String optimizedValue) { this.optimizedValue = optimizedValue; } public Double getOptimizedSetting() { return optimizedSetting; } public void setOptimizedSetting(Double optimizedSetting) { this.optimizedSetting = optimizedSetting; } public String getFileContent() { return fileContent; } public void setFileContent(String fileContent) { this.fileContent = fileContent; } public boolean isFileWritten() { return fileWritten; } public void setFileWritten(boolean fileWritten) { this.fileWritten = fileWritten; } public Map<String, Object> getParsedJson() { return parsedJson; } public void setParsedJson(Map<String, Object> parsedJson) { this.parsedJson = parsedJson; } public String getJsonString() { return jsonString; } public void setJsonString(String jsonString) { this.jsonString = jsonString; } public boolean isValid() { return isValid; } public void setValid(boolean valid) { isValid = valid; } public boolean isEmailValid() { return isEmailValid; } public void setEmailValid(boolean emailValid) { isEmailValid = emailValid; } public String getEncryptedData() { return encryptedData; } public void setEncryptedData(String encryptedData) { this.encryptedData = encryptedData; } public String getDecryptedData() { return decryptedData; } public void setDecryptedData(String decryptedData) { this.decryptedData = decryptedData; } }

// @ operator context for Java integration public class AtOperatorContext { private Map<String, AtOperator> operators; private AtOperatorExecutor executor; public AtOperatorContext() { this.operators = new ConcurrentHashMap<>(); this.executor = new AtOperatorExecutor(); } // Register @ operator public void registerOperator(String name, AtOperator operator) { operators.put(name, operator); } // Execute @ operator public Object execute(String operator, String... parameters) { AtOperator op = operators.get(operator); if (op == null) { throw new AtOperatorException("Unknown @ operator: " + operator); } return executor.execute(op, parameters); } // Get registered operators public Set<String> getRegisteredOperators() { return new HashSet<>(operators.keySet()); } }

// @ operator interface public interface AtOperator { Object execute(String... parameters) throws Exception; String getName(); String getDescription(); }

// @ operator executor public class AtOperatorExecutor { public Object execute(AtOperator operator, String... parameters) throws Exception { try { return operator.execute(parameters); } catch (Exception e) { throw new AtOperatorException("Failed to execute @ operator: " + operator.getName(), e); } } }

TuskLang @ Operator Examples

@ Operator examples in TuskLang configuration

Environment variable operators

database_host: string = @env("DB_HOST", "localhost") database_port: number = @env("DB_PORT", 5432) database_name: string = @env("DB_NAME", "tuskdb") database_user: string = @env("DB_USER", "postgres") database_password: string = @env.secure("DB_PASSWORD")

Database query operators

user_count: number = @query("SELECT COUNT(*) FROM users") active_users: number = @query("SELECT COUNT(*) FROM users WHERE active = true") recent_user: string = @query("SELECT name FROM users ORDER BY created_at DESC LIMIT 1") user_by_id: object = @query("SELECT * FROM users WHERE id = ?", @env("USER_ID"))

HTTP request operators

api_status: string = @http("GET", "https://api.example.com/status") api_data: object = @http("POST", "https://api.example.com/data", { "key": "value" "timestamp": @date.now() }) api_headers: object = @http.headers("https://api.example.com/headers")

Date and time operators

current_time: string = @date.now() formatted_date: string = @date("Y-m-d H:i:s") timestamp: number = @date.timestamp() yesterday: string = @date.subtract("1d") next_week: string = @date.add("7d")

Cache operators

cached_value: string = @cache("5m", "expensive_operation") cached_user: object = @cache("1h", @query("SELECT * FROM users WHERE id = ?", 1)) cached_api: string = @cache("10m", @http("GET", "https://api.example.com/data"))

Metrics operators

response_time: number = @metrics("api_response_time_ms", 150) error_rate: number = @metrics("error_rate_percent", 2.5) throughput: number = @metrics("requests_per_second", 1000)

Machine learning operators

optimal_setting: number = @learn("optimal_cache_size", 100) predicted_load: number = @learn("predicted_user_load", 500) optimized_timeout: number = @optimize("connection_timeout", 30)

File operators

config_content: string = @file.read("config.json") log_content: string = @file.read("logs/app.log") file_written: boolean = @file.write("output.txt", "Hello World") file_exists: boolean = @file.exists("important.txt")

JSON operators

parsed_config: object = @json.parse(@file.read("config.json")) json_string: string = @json.stringify({ "name": "TuskLang" "version": "1.0.0" "features": ["@operators", "database", "http"] })

Validation operators

is_valid_email: boolean = @validate.email("user@example.com") is_valid_url: boolean = @validate.url("https://example.com") is_required: boolean = @validate.required(["api_key", "database_url"]) is_in_range: boolean = @validate.range(42, 1, 100)

Encryption operators

encrypted_password: string = @encrypt("sensitive_password", "AES-256-GCM") decrypted_password: string = @decrypt(@encrypted_password, "AES-256-GCM") hashed_value: string = @hash("value_to_hash", "SHA-256")

Conditional operators

environment: string = @if(@env("NODE_ENV") == "production", "prod", "dev") debug_mode: boolean = @if(@env("DEBUG") == "true", true, false) fallback_value: string = @env("API_KEY") || "default_key"

Mathematical operators

sum: number = @math.add(10, 20, 30) average: number = @math.avg([1, 2, 3, 4, 5]) random_number: number = @math.random(1, 100) rounded_value: number = @math.round(3.14159, 2)

String operators

uppercase_name: string = @string.upper("tusklang") lowercase_name: string = @string.lower("TUSKLANG") trimmed_value: string = @string.trim(" hello world ") replaced_text: string = @string.replace("hello world", "world", "TuskLang")

🔧 @ Operator Categories

Java @ Operator Implementation

@TuskConfig
public class AtOperatorCategories {
    
    // Environment operators
    @TuskOperator("@env")
    private EnvironmentOperators envOps;
    
    // Database operators
    @TuskOperator("@query")
    private DatabaseOperators dbOps;
    
    // HTTP operators
    @TuskOperator("@http")
    private HttpOperators httpOps;
    
    // Date operators
    @TuskOperator("@date")
    private DateOperators dateOps;
    
    // Cache operators
    @TuskOperator("@cache")
    private CacheOperators cacheOps;
    
    // Metrics operators
    @TuskOperator("@metrics")
    private MetricsOperators metricsOps;
    
    // ML operators
    @TuskOperator("@learn")
    private MachineLearningOperators mlOps;
    
    // File operators
    @TuskOperator("@file")
    private FileOperators fileOps;
    
    // JSON operators
    @TuskOperator("@json")
    private JsonOperators jsonOps;
    
    // Validation operators
    @TuskOperator("@validate")
    private ValidationOperators validationOps;
    
    // Encryption operators
    @TuskOperator("@encrypt")
    private EncryptionOperators encryptionOps;
    
    // Mathematical operators
    @TuskOperator("@math")
    private MathOperators mathOps;
    
    // String operators
    @TuskOperator("@string")
    private StringOperators stringOps;
    
    // Conditional operators
    @TuskOperator("@if")
    private ConditionalOperators conditionalOps;
    
    // Getters and setters
    public EnvironmentOperators getEnvOps() { return envOps; }
    public void setEnvOps(EnvironmentOperators envOps) { this.envOps = envOps; }
    
    public DatabaseOperators getDbOps() { return dbOps; }
    public void setDbOps(DatabaseOperators dbOps) { this.dbOps = dbOps; }
    
    public HttpOperators getHttpOps() { return httpOps; }
    public void setHttpOps(HttpOperators httpOps) { this.httpOps = httpOps; }
    
    public DateOperators getDateOps() { return dateOps; }
    public void setDateOps(DateOperators dateOps) { this.dateOps = dateOps; }
    
    public CacheOperators getCacheOps() { return cacheOps; }
    public void setCacheOps(CacheOperators cacheOps) { this.cacheOps = cacheOps; }
    
    public MetricsOperators getMetricsOps() { return metricsOps; }
    public void setMetricsOps(MetricsOperators metricsOps) { this.metricsOps = metricsOps; }
    
    public MachineLearningOperators getMlOps() { return mlOps; }
    public void setMlOps(MachineLearningOperators mlOps) { this.mlOps = mlOps; }
    
    public FileOperators getFileOps() { return fileOps; }
    public void setFileOps(FileOperators fileOps) { this.fileOps = fileOps; }
    
    public JsonOperators getJsonOps() { return jsonOps; }
    public void setJsonOps(JsonOperators jsonOps) { this.jsonOps = jsonOps; }
    
    public ValidationOperators getValidationOps() { return validationOps; }
    public void setValidationOps(ValidationOperators validationOps) { this.validationOps = validationOps; }
    
    public EncryptionOperators getEncryptionOps() { return encryptionOps; }
    public void setEncryptionOps(EncryptionOperators encryptionOps) { this.encryptionOps = encryptionOps; }
    
    public MathOperators getMathOps() { return mathOps; }
    public void setMathOps(MathOperators mathOps) { this.mathOps = mathOps; }
    
    public StringOperators getStringOps() { return stringOps; }
    public void setStringOps(StringOperators stringOps) { this.stringOps = stringOps; }
    
    public ConditionalOperators getConditionalOps() { return conditionalOps; }
    public void setConditionalOps(ConditionalOperators conditionalOps) { this.conditionalOps = conditionalOps; }
}

// Environment operators public class EnvironmentOperators { public String get(String key) { return System.getenv(key); } public String get(String key, String defaultValue) { String value = System.getenv(key); return value != null ? value : defaultValue; } public String getSecure(String key) { // Implement secure environment variable access return System.getenv(key); } public int getInt(String key, int defaultValue) { String value = System.getenv(key); try { return value != null ? Integer.parseInt(value) : defaultValue; } catch (NumberFormatException e) { return defaultValue; } } public boolean getBoolean(String key, boolean defaultValue) { String value = System.getenv(key); return value != null ? Boolean.parseBoolean(value) : defaultValue; } }

// Database operators public class DatabaseOperators { private DataSource dataSource; public DatabaseOperators(DataSource dataSource) { this.dataSource = dataSource; } public Object query(String sql, Object... parameters) { try (Connection conn = dataSource.getConnection(); PreparedStatement stmt = conn.prepareStatement(sql)) { for (int i = 0; i < parameters.length; i++) { stmt.setObject(i + 1, parameters[i]); } ResultSet rs = stmt.executeQuery(); return convertResultSetToObject(rs); } catch (SQLException e) { throw new RuntimeException("Database query failed", e); } } private Object convertResultSetToObject(ResultSet rs) throws SQLException { // Convert ResultSet to appropriate object return null; } }

// HTTP operators public class HttpOperators { private HttpClient httpClient; public HttpOperators() { this.httpClient = HttpClient.newHttpClient(); } public String get(String url) { try { HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .GET() .build(); HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString()); return response.body(); } catch (Exception e) { throw new RuntimeException("HTTP GET failed", e); } } public String post(String url, String body) { try { HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .POST(HttpRequest.BodyPublishers.ofString(body)) .header("Content-Type", "application/json") .build(); HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString()); return response.body(); } catch (Exception e) { throw new RuntimeException("HTTP POST failed", e); } } }

TuskLang @ Operator Categories

@ Operator categories in TuskLang

1. Environment Operators

env_variable: string = @env("API_KEY") env_with_default: string = @env("DEBUG", "false") secure_env: string = @env.secure("SECRET_KEY") env_as_number: number = @env("PORT", 8080) env_as_boolean: boolean = @env("ENABLE_FEATURE", true)

2. Database Operators

user_count: number = @query("SELECT COUNT(*) FROM users") user_by_id: object = @query("SELECT * FROM users WHERE id = ?", 1) recent_orders: array = @query("SELECT * FROM orders WHERE created_at > ?", @date.subtract("7d")) complex_query: object = @query(""" SELECT u.name, COUNT(o.id) as order_count FROM users u LEFT JOIN orders o ON u.id = o.user_id WHERE u.active = true GROUP BY u.id, u.name """)

3. HTTP Operators

api_status: string = @http("GET", "https://api.example.com/status") api_data: object = @http("POST", "https://api.example.com/data", { "user_id": 1 "action": "login" "timestamp": @date.now() }) api_with_headers: string = @http("GET", "https://api.example.com/protected", { "headers": { "Authorization": "Bearer " + @env("API_TOKEN") "Content-Type": "application/json" } })

4. Date Operators

current_time: string = @date.now() formatted_date: string = @date("Y-m-d H:i:s") timestamp: number = @date.timestamp() yesterday: string = @date.subtract("1d") next_week: string = @date.add("7d") start_of_month: string = @date.startOf("month") end_of_year: string = @date.endOf("year")

5. Cache Operators

cached_value: string = @cache("5m", "expensive_operation") cached_query: object = @cache("1h", @query("SELECT * FROM users WHERE id = ?", 1)) cached_http: string = @cache("10m", @http("GET", "https://api.example.com/data")) cached_with_key: string = @cache("user_data", "30m", @query("SELECT * FROM users"))

6. Metrics Operators

response_time: number = @metrics("api_response_time_ms", 150) error_rate: number = @metrics("error_rate_percent", 2.5) throughput: number = @metrics("requests_per_second", 1000) custom_metric: number = @metrics("custom_business_metric", 42)

7. Machine Learning Operators

optimal_setting: number = @learn("optimal_cache_size", 100) predicted_load: number = @learn("predicted_user_load", 500) optimized_timeout: number = @optimize("connection_timeout", 30) smart_default: string = @learn("user_preference", "default_value")

8. File Operators

config_content: string = @file.read("config.json") log_content: string = @file.read("logs/app.log") file_written: boolean = @file.write("output.txt", "Hello World") file_exists: boolean = @file.exists("important.txt") file_size: number = @file.size("large_file.dat") file_modified: string = @file.modified("config.json")

9. JSON Operators

parsed_config: object = @json.parse(@file.read("config.json")) json_string: string = @json.stringify({ "name": "TuskLang" "version": "1.0.0" "features": ["@operators", "database", "http"] }) json_merge: object = @json.merge(@file.read("base.json"), @file.read("override.json")) json_path: string = @json.path(@parsed_config, "database.host")

10. Validation Operators

is_valid_email: boolean = @validate.email("user@example.com") is_valid_url: boolean = @validate.url("https://example.com") is_required: boolean = @validate.required(["api_key", "database_url"]) is_in_range: boolean = @validate.range(42, 1, 100) is_valid_format: boolean = @validate.format("2023-12-19", "Y-m-d")

11. Encryption Operators

encrypted_password: string = @encrypt("sensitive_password", "AES-256-GCM") decrypted_password: string = @decrypt(@encrypted_password, "AES-256-GCM") hashed_value: string = @hash("value_to_hash", "SHA-256") signed_data: string = @sign("data_to_sign", "HMAC-SHA256")

12. Mathematical Operators

sum: number = @math.add(10, 20, 30) average: number = @math.avg([1, 2, 3, 4, 5]) random_number: number = @math.random(1, 100) rounded_value: number = @math.round(3.14159, 2) power: number = @math.pow(2, 10) square_root: number = @math.sqrt(16)

13. String Operators

uppercase_name: string = @string.upper("tusklang") lowercase_name: string = @string.lower("TUSKLANG") trimmed_value: string = @string.trim(" hello world ") replaced_text: string = @string.replace("hello world", "world", "TuskLang") substring: string = @string.substring("Hello World", 0, 5) split_text: array = @string.split("a,b,c", ",") joined_text: string = @string.join(["a", "b", "c"], "-")

14. Conditional Operators

environment: string = @if(@env("NODE_ENV") == "production", "prod", "dev") debug_mode: boolean = @if(@env("DEBUG") == "true", true, false) fallback_value: string = @env("API_KEY") || "default_key" conditional_config: object = @if(@env("ENVIRONMENT") == "production", { "ssl": true "cache": true "monitoring": true }, { "ssl": false "cache": false "monitoring": false })

🎯 Best Practices

@ Operator Guidelines

1. Use appropriate operators for your use case 2. Handle errors gracefully with fallback values 3. Cache expensive operations for performance 4. Validate operator inputs before execution 5. Use secure operators for sensitive data 6. Monitor operator performance and usage 7. Document operator usage in your configurations 8. Test operator behavior in all environments 9. Use type-safe operators when possible 10. Implement proper error handling for all operators

Performance Considerations

// Efficient @ operator usage
@TuskConfig
public class EfficientAtOperators {
    
    // Cache expensive operations
    @TuskOperator("@cache")
    private String expensiveOperation;
    
    // Use connection pooling for database operations
    @TuskOperator("@query")
    private Object databaseQuery;
    
    // Implement retry logic for HTTP operations
    @TuskOperator("@http")
    private String httpRequest;
    
    // Use async operations where appropriate
    @TuskOperator("@async")
    private CompletableFuture<String> asyncOperation;
}

🚨 Troubleshooting

Common @ Operator Issues

1. Environment variables not found: Use default values 2. Database connection failures: Implement retry logic 3. HTTP request timeouts: Set appropriate timeouts 4. Cache misses: Implement fallback strategies 5. Validation failures: Provide clear error messages

Debug @ Operator Issues

// Debug @ operator problems
public void debugAtOperators() {
    System.out.println("Environment variables:");
    System.out.println("  DB_HOST: " + System.getenv("DB_HOST"));
    System.out.println("  API_KEY: " + (System.getenv("API_KEY") != null ? "SET" : "NOT SET"));
    
    System.out.println("Database connection:");
    try {
        // Test database connection
        System.out.println("  Status: CONNECTED");
    } catch (Exception e) {
        System.out.println("  Status: FAILED - " + e.getMessage());
    }
    
    System.out.println("HTTP endpoints:");
    try {
        // Test HTTP endpoints
        System.out.println("  Status: AVAILABLE");
    } catch (Exception e) {
        System.out.println("  Status: FAILED - " + e.getMessage());
    }
}

🎯 Next Steps

1. Explore specific @ operators in detail 2. Learn about operator chaining and composition 3. Master error handling for @ operators 4. Implement custom @ operators for your needs 5. Optimize @ operator performance in your applications

---

Ready to master @ operators with Java power? The @ operator system is the heart of TuskLang's dynamic configuration capabilities. We don't bow to any king - especially not static configuration!