flowlang-script 1.0.1

A lightweight interpreted programming language for workflow automation and API orchestration

FlowLang

A lightweight interpreted programming language designed for workflow automation, data processing, and API orchestration.

Table of Contents

• Overview
• Installation
• Quick Start
• Language Specification
• Built-in Functions
• Usage Examples
• API Reference
• Use Cases
• Integration
• Contributing
• License

Overview

FlowLang is a domain-specific programming language built to address the complexity of workflow automation and API orchestration. It provides a clean, minimal syntax that prioritizes readability and ease of use while maintaining powerful capabilities for data processing tasks.

Design Philosophy

• Simplicity First: Minimal syntax that's easy to learn and read
• Zero Dependencies: Built entirely on Python's standard library
• Practical: Focused on real-world automation tasks
• Readable: Code that serves as its own documentation

Key Features

• Native HTTP request capabilities (http_get, http_post)
• Built-in file I/O operations
• First-class functions with return values
• Control flow structures (if, while)
• Rich set of built-in utility functions
• Automatic JSON parsing for API responses
• String escape sequence support

Installation

From PyPI (Recommended)

pip install flowlang-script

From Source

git clone https://github.com/ChilliRoger/flowlang.git
cd flowlang
pip install -e .

Verify Installation

flow run --help

Quick Start

Hello World

Create a file hello.flow:

print "Hello, World!"

Run it:

flow run hello.flow

Basic Operations

let x = 10
let y = 20
let sum = x + y
print sum

HTTP Request Example

let response = http_get("https://api.github.com")
print response

Language Specification

Variables

Variables are declared using the let keyword and are dynamically typed.

let name = "FlowLang-Script"
let version = 1
let pi = 3.14

Data Types

• Integer: Whole numbers (42, -10)
• String: Text enclosed in double quotes ("hello")
• List: Returned by built-in functions like range()
• Dictionary: Returned by JSON parsing in HTTP responses

Operators

Arithmetic Operators

Operator	Description	Example
+	Addition	5 + 3 returns 8
-	Subtraction	10 - 4 returns 6
*	Multiplication	3 * 4 returns 12
/	Division	15 / 3 returns 5

Comparison Operators

Operator	Description	Example
<	Less than	5 < 10 returns true
>	Greater than	10 > 5 returns true
<=	Less than or equal	5 <= 5 returns true
>=	Greater than or equal	10 >= 5 returns true
==	Equal to	5 == 5 returns true
!=	Not equal to	5 != 3 returns true

Control Flow

If Statements

let age = 18
if age >= 18 {
  print "Adult"
}

While Loops

let count = 5
while count > 0 {
  print count
  let count = count - 1
}

Functions

Functions are defined using the func keyword and support parameters and return values.

func add(a, b) {
  return a + b
}

let result = add(10, 20)
print result

Function Scope

Functions have their own local scope. Variables passed as arguments are local to the function.

func increment(x) {
  let x = x + 1
  return x
}

let value = 5
let newValue = increment(value)
print newValue  # Prints 6
print value     # Prints 5 (unchanged)

Comments

FlowLang currently does not support inline comments. Use descriptive variable and function names for self-documenting code.

Built-in Functions

I/O Functions

print(value)

Outputs a value to the console.

print "Hello"
print 42

input(prompt)

Reads user input from the console.

let name = input("Enter your name: ")
print name

Type Conversion Functions

str(value)

Converts a value to a string.

let num = 42
let text = str(num)

int(value)

Converts a value to an integer.

let text = "123"
let num = int(text)

type(value)

Returns the type name of a value as a string.

print type(42)        # Prints: int
print type("hello")   # Prints: str

Utility Functions

len(value)

Returns the length of a string or list.

let text = "FlowLang-Script"
print len(text)  # Prints: 15

range(start, end)

Creates a list of integers from start (inclusive) to end (exclusive).

let numbers = range(1, 5)
print numbers  # Prints: [1, 2, 3, 4]

HTTP Functions

http_get(url)

Performs an HTTP GET request and returns the response.

let data = http_get("https://jsonplaceholder.typicode.com/users/1")
print data

Features:

• Automatic JSON parsing when possible
• Returns dictionary for JSON responses
• Returns string for plain text responses
• Error handling with error messages

http_post(url, data)

Performs an HTTP POST request with JSON data.

let response = http_post("https://api.example.com/data", {"key": "value"})
print response

File I/O Functions

read_file(path)

Reads and returns the contents of a file.

let content = read_file("data.txt")
print content

write_file(path, content)

Writes content to a file.

let result = write_file("output.txt", "Hello, World!")
print result  # Prints: Written to output.txt

Usage Examples

Example 1: Simple Calculator

func calculate(a, b, operation) {
  if operation == "add" {
    return a + b
  }
  if operation == "subtract" {
    return a - b
  }
  if operation == "multiply" {
    return a * b
  }
  if operation == "divide" {
    return a / b
  }
  return 0
}

let result = calculate(10, 5, "add")
print result

Example 2: API Data Fetching

let user = http_get("https://jsonplaceholder.typicode.com/users/1")
let filename = "user_data.txt"
write_file(filename, str(user))
print "Data saved successfully"

Example 3: Batch Processing

func process_item(id) {
  let url = "https://jsonplaceholder.typicode.com/todos/" + str(id)
  let data = http_get(url)
  let filename = "item_" + str(id) + ".txt"
  write_file(filename, str(data))
  return "Processed item " + str(id)
}

let count = 1
while count <= 3 {
  let status = process_item(count)
  print status
  let count = count + 1
}

Example 4: Data Transformation Pipeline

func fetch_and_transform() {
  print "Fetching data..."
  let raw_data = http_get("https://jsonplaceholder.typicode.com/posts/1")
  
  print "Processing data..."
  let processed = str(raw_data)
  
  print "Saving results..."
  write_file("processed_data.txt", processed)
  
  return "Pipeline complete"
}

let status = fetch_and_transform()
print status

API Reference

Command Line Interface

flow run <script.flow>

Arguments:

• <script.flow>: Path to the FlowLang script file

Examples:

flow run examples/basic.flow
flow run workflow.flow

Programmatic Usage

FlowLang can be embedded in Python applications:

from flowlang.lexer import Lexer
from flowlang.parser import Parser
from flowlang.interpreter import Interpreter

# Your FlowLang-Script code
code = """
let x = 10
let y = 20
print x + y
"""

# Execute
tokens = Lexer(code).tokens
ast = Parser(tokens).parse()
Interpreter().eval(ast)

Custom Built-in Functions

Extend FlowLang with custom built-in functions:

from flowlang.interpreter import Interpreter

interp = Interpreter()

# Add custom function
interp.builtins['custom_func'] = lambda args: args[0] * 2

# Execute code that uses it
code = "print custom_func(21)"
tokens = Lexer(code).tokens
ast = Parser(tokens).parse()
interp.eval(ast)

Use Cases

1. API Testing and Validation

FlowLang excels at quick API testing without the overhead of larger frameworks.

let endpoint = "https://api.example.com/health"
let response = http_get(endpoint)
print "API Status:"
print response

2. Data Pipeline Automation

Create ETL (Extract, Transform, Load) workflows with minimal code.

func etl_pipeline(source_id) {
  let data = http_get("https://api.source.com/data/" + str(source_id))
  let transformed = str(data)
  write_file("output_" + str(source_id) + ".txt", transformed)
  return "Complete"
}

let ids = range(1, 10)
let i = 1
while i < 10 {
  etl_pipeline(i)
  let i = i + 1
}

3. Configuration Management

Automate configuration file generation and updates.

func generate_config(env) {
  let config = "environment=" + env
  write_file(env + "_config.txt", config)
  return "Config generated for " + env
}

generate_config("production")
generate_config("staging")

4. Microservice Orchestration

Coordinate calls across multiple microservices.

func orchestrate() {
  let users = http_get("https://api.service1.com/users")
  let orders = http_get("https://api.service2.com/orders")
  
  write_file("users.txt", str(users))
  write_file("orders.txt", str(orders))
  
  return "Orchestration complete"
}

orchestrate()

5. Scheduled Tasks and Cron Jobs

Perfect for periodic data collection and processing tasks.

func daily_report() {
  let data = http_get("https://api.example.com/daily-stats")
  let timestamp = str(data)
  write_file("daily_report.txt", timestamp)
  return "Report generated"
}

daily_report()

Integration

Integration with Python Projects

FlowLang can be embedded in Python applications for scriptable automation.

Example: Flask Integration

from flask import Flask, request
from flowlang.lexer import Lexer
from flowlang.parser import Parser
from flowlang.interpreter import Interpreter

app = Flask(__name__)

@app.route('/execute', methods=['POST'])
def execute_flowlang():
    code = request.json.get('code')
    
    tokens = Lexer(code).tokens
    ast = Parser(tokens).parse()
    Interpreter().eval(ast)
    
    return {'status': 'success'}

Integration with CI/CD Pipelines

Use FlowLang scripts in continuous integration workflows.

Example: GitHub Actions

name: Run FlowLang Script
on: [push]
jobs:
  run-script:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Python
        uses: actions/setup-python@v2
      - name: Install FlowLang
        run: pip install flowlang
      - name: Execute Script
        run: flow run scripts/deploy.flow

Integration with Docker

Create containerized FlowLang execution environments.

Dockerfile Example:

FROM python:3.9-slim

WORKDIR /app

RUN pip install flowlang

COPY scripts/ /app/scripts/

CMD ["flow", "run", "scripts/main.flow"]

Integration with Scheduling Systems

Use with cron or systemd timers for scheduled execution.

Cron Example:

# Run daily report at 9 AM
0 9 * * * /usr/local/bin/flow run /home/user/reports/daily.flow

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Make your changes
4. Run tests to ensure compatibility
5. Commit your changes (git commit -am 'Add new feature')
6. Push to the branch (git push origin feature/new-feature)
7. Create a Pull Request

Development Setup

git clone https://github.com/ChilliRoger/flowlang.git
cd flowlang
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Running Tests

flow run examples/test_all.flow

License

MIT License

Copyright (c) 2025 FlowLang

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Support and Resources

• Documentation: See QUICKREF.md for quick reference
• Examples: Check the examples/ directory for sample scripts
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

FlowLang is built with Python and relies on the Python standard library for all functionality. Special thanks to the open-source community for inspiration and support.