boxlang-modules-and-packages

BoxLang 模块和包

BoxLang 是一个 AI 原生软件生产力平台，用于构建、现代化改造和运行应用程序，让开发者与 AI Agent 携手协作。

概述

BoxLang 的模块系统可通过额外的内置函数（BIF）、组件和服务扩展运行时。模块通过 CommandBox 的 box CLI 安装，并在 boxlang.json 或 Application.bx 中配置。许多模块会自动全局注册其 BIF——安装后无需导入。

安装模块

# Install via CommandBox
box install bx-redis
box install bx-pdf
box install bx-csv
box install bx-spreadsheet

# Install a specific version
box install [email protected]

# Install multiple at once
box install bx-redis bx-csv bx-mail

# List installed modules
box list

在 boxlang.json 中配置模块

{
    "modules": {
        "bx-redis": {
            "enabled": true,
            "settings": {
                "host": "${REDIS_HOST:localhost}",
                "port": 6379,
                "password": "${REDIS_PASSWORD:}"
            }
        },
        "bx-mail": {
            "enabled": true,
            "settings": {
                "spooling": true,
                "serverInterval": 5000,
                "smtp": {
                    "host": "${SMTP_HOST}",
                    "port": 587,
                    "tls": true,
                    "auth": true,
                    "username": "${SMTP_USER}",
                    "password": "${SMTP_PASS}"
                }
            }
        },
        "compat-cfml": {
            "enabled": true,
            "settings": {
                "engine": "Lucee"
            }
        }
    }
}

禁用模块

{
    "modules": {
        "bx-orm": {
            "enabled": false
        }
    }
}

---

核心免费模块

bx-compat-cfml — CFML 兼容性

启用 CFML 语法解析以及 CFML 专用函数和组件，以便迁移旧版 ColdFusion 或 Lucee 应用程序：

{
    "modules": {
        "compat-cfml": {
            "enabled": true,
            "settings": { "engine": "Lucee" }
        }
    }
}

启用后，.cfm、.cfc 和 CFML 语法会与 BoxLang 语法一同得到识别。

bx-web-support — Web 服务器集成

提供 Web 请求/响应处理、会话管理和 CGI 作用域支持。任何 Web 应用程序都需要此模块。通常由 CommandBox/MiniServer 自动加载。

bx-mail — 电子邮件

// Send an email
bx:mail
    to="[email protected]"
    from="[email protected]"
    subject="Welcome to MyApp!"
    type="html" {

    writeOutput( "<h1>Welcome, #name#!</h1>" )
    writeOutput( "<p>Your account is ready.</p>" )
}

// Plain text with attachment
bx:mail to="[email protected]" from="[email protected]" subject="Report" {
    bx:mailpart type="text" {
        writeOutput( "See attached report." )
    }
    bx:mailparam file=expandPath("./reports/daily.pdf") disposition="attachment"
}

bx-orm — 对象关系映射（Hibernate）

// In Application.bx
class {
    this.ormEnabled = true
    this.ormSettings = {
        datasource      : "mainDB",
        dbcreate        : "update",
        flushAtRequestEnd : true,
        autoManageSession : true
    }
}

// Persistent entity: models/User.bx
class persistent="true" table="users" accessors="true" {
    property name="id"    column="id"    fieldtype="id" generator="native"
    property name="name"  column="name"  type="string"
    property name="email" column="email" type="string"

    // Relationship
    property name="orders" fieldtype="one-to-many" cfc="models.Order"
              cascade="all" lazy="true"
}

// ORM operations
var user = entityLoad( "User", userId )
entitySave( new models.User( name="Ada", email="[email protected]" ) )
entityDelete( user )

// HQL queries
var users = ORMExecuteQuery( "FROM User WHERE status = :status", { status: "active" } )

---

BoxLang+ 高级模块

BoxLang+ 模块需要在 boxlang.io 订阅。

bx-pdf — PDF 生成

// Generate PDF from HTML
bx:pdf action="write" filename=expandPath("./output/report.pdf") overwrite="true" {
    bx:pdfparam type="header" {
        writeOutput( "<h3>Monthly Report</h3>" )
    }
    writeOutput( "<h1>Sales Summary</h1>" )
    writeOutput( "<p>Total: $#totalSales#</p>" )
    include "views/sales-table.bxm"
}

// Merge PDFs
bx:pdf action="merge" destination=expandPath("./merged.pdf") overwrite="true" {
    bx:pdfparam source=expandPath("./cover.pdf")
    bx:pdfparam source=expandPath("./report.pdf")
}

bx-csv — CSV 处理

// Parse CSV
var data = csvParse( fileRead("data.csv") )

// Parse with options
var data = csvParse(
    fileRead( "data.csv" ),
    {
        hasHeaders   : true,
        delimiter    : ",",
        quoteChar    : '"',
        charset      : "UTF-8"
    }
)

// Iterate rows
for ( var row in data ) {
    processRow( row )
}

// Generate CSV
var output = csvSerialize(
    queryExecute( "SELECT id, name, email FROM users" ),
    { hasHeaders: true, delimiter: "," }
)
fileWrite( "export.csv", output )

bx-spreadsheet — Excel（XLSX）

// Read a spreadsheet
var wb = spreadsheetRead( expandPath("./data.xlsx") )
var sheet = spreadsheetGetSheetName( wb, 1 )
var data  = spreadsheetRead( expandPath("./data.xlsx"), true, true )

// Create a spreadsheet
var wb = spreadsheetNew( "Report" )
spreadsheetAddRow( wb, ["Name", "Email", "Revenue"] )

for ( var user in users ) {
    spreadsheetAddRow( wb, [user.name, user.email, user.revenue] )
}

// Format header row
spreadsheetFormatRow( wb, {
    bold       : true,
    bgcolor    : "##336699",
    fontcolor  : "##FFFFFF"
}, 1 )

spreadsheetWrite( wb, expandPath("./report.xlsx") )

bx-redis — Redis 集成

// After configuring the module, use Redis as a cache provider
// (see caching skill for full details)

// Direct Redis operations via the Redis client
var redis = getBoxService( "RedisService" )
redis.set( "key", "value", 3600 )  // with TTL in seconds
var val = redis.get( "key" )
redis.del( "key" )
redis.incr( "counter" )
redis.lpush( "queue", jsonSerialize(job) )
var job = redis.rpop( "queue" )

bx-ldap — LDAP 目录

bx:ldap
    server="ldap.example.com"
    port="389"
    username="cn=admin,dc=example,dc=com"
    password="#ldapPassword#"
    action="query"
    name="result"
    start="dc=example,dc=com"
    attributes="cn,mail,sn"
    filter="(objectClass=person)"

for ( var person in result ) {
    writeOutput( "#person.cn# — #person.mail#<br>" )
}

bx-audio — 音频

// Make a tone, fade it, save it, inspect it
tone = audioOsc( "sine", 440, 1 )
tone = audioFade( audio=tone, fadeIn=0.01, fadeOut=0.2, curve="smooth" )
audioSave( tone, "tone.wav" )
println( audioInfo( "tone.wav" ) )

// Master a recording to the podcast loudness standard
audioSave( audioMaster( audio=audioLoad( "episode.wav" ), target="podcast" ), "episode-mastered.wav" )

安装 bx-ai 后，bx-audio 还会注册 Agent 工具（audioTrim@bxaudio 等另外 25 个）。请参阅 bx-audio 技能。

bx-image — 图像处理

// Read and resize
var img = imageRead( expandPath("./upload/photo.jpg") )
imageResize( img, 800, 600 )
imageWrite( img, expandPath("./output/photo-resized.jpg") )

// Crop
imageCrop( img, x=0, y=0, width=400, height=300 )

// Add watermark
var watermark = imageNew( "", 200, 50, "argb", "##00000000" )
imageDrawText( watermark, "© 2024 MyApp", 10, 30, { size: 16, color: "##FFFFFF" } )
imagePaste( img, watermark, 600, 550 )

// Get info
var info = imageInfo( img )
writeOutput( "Width: #info.width#, Height: #info.height#" )

---

模块自省

// List all loaded modules
var modules = getBoxService( "ModuleService" ).getLoadedModules()
modules.each( (name) -> writeOutput( name & "<br>" ) )

// Get module info
var info = getModuleInfo( "bx-redis" )
writeOutput( "Version: #info.version#" )
writeOutput( "Author: #info.author#" )

// Check if a module is loaded
if ( isModuleLoaded( "bx-redis" ) ) {
    // use Redis
}

参考资料

• 模块化
• 模块配置
• BoxLang+ 模块
• ForgeBox 包管理器
• bx-pdf
• bx-csv
• bx-spreadsheet