FIBOS IDL文件初探
Opened this issue · 0 comments
初探 IDL
在前不久,FIBOS 向社区开源了 IDL 文件,你可以在 GitHub 里查看它们。那么 IDL 对 FIBOS 来说意味着什么,我们开发者使用 IDL 又能做什么呢?本文将带你一探究竟。
所谓 IDL 就是接口描述语言(Interface description language),指描述某一种变成语言的接口的文件。一般用于对外声明接口起到文档的作用,同时可以用来编译成某种语言的代码。
更具象的来谈,我们知道 FIBOS 是基于 Fibjs + EOS 的,所以在 FIBOS 体系中,IDL 文件描述了 Fibjs 的对象和模块的结构,用它可以生成头文件和对应的文档。然后 FIBOS 将其注册到自己的沙箱中,从而可以在 JavaScript 中调用 FIBOS 提供的模块和方法。今天仅仅介绍 IDL 文件的构成和使用方法。
解析 IDL
在阅读 IDL 之前,我们首先需要了解一下在 FIBOS 中 IDL 支持哪些数据类型。IDL 支持两种类型:
- 内置的字典集。在生成头文件的过程中,生成工具可以将 IDL 中的类型转换成 C++中头文件中对应的类型,它们是:
var typeMap = {
"Integer": "int32_t",
"Long": "int64_t",
"Number": "double",
"Boolean": "bool",
"String": "exlib::string",
"Date": "date_t",
"Object": "v8::Local<v8::Object>",
"Iterator": "v8::Local<v8::Object>",
"Array": "v8::Local<v8::Array>",
"TypedArray": "v8::Local<v8::TypedArray>",
"ArrayBuffer": "v8::Local<v8::ArrayBuffer>",
"ArrayBufferView": "v8::Local<v8::ArrayBufferView>",
"Function": "v8::Local<v8::Function>",
"Value": "v8::Local<v8::Value>",
"Variant": "Variant",
"NObject": "obj_ptr<NObject>",
"NArray": "obj_ptr<NArray>",
"...": "OptArgs"
};
- 自己定义的数据类型。IDL 在生成的头文件中会自动引入
xxxx_base
的文件,并使用其中的方法。
小试牛刀
我们以一个简单的例子开始。下面我定义了一个name
的 IDL 文件,它提供两个方法。
check
方法,其参数是一个String
,默认的字典类型,用来判断所传入的字符串是否等于“FIBOS”,返回值是boolean
类型sha256
方法,其参数是我们自己定义Buffer
类型,用来创建一个 SHA256 信息摘要运算对象。
文件实例如下:
/*! @brief
name 对象
*/
module name {
/*! @brief 检测字符串是否为 FIBOS
@param String text 所需检验的字符
*/
static Boolean check(String text);
/*! @brief 创建一个 SHA256 信息摘要运算对象
@param data 创建同时更新的二进制数据
*/
static String sha256(Buffer data);
};
你可以在 tools 目录下执行fibos idlc.js
,该文件会读取 idl 目录下的所有 idl 文件并进行解析,生成对应的头文件。这些生成的头文件会存放在在 fibos/include/ifs
目录下,执行后生成文件如下:
/***************************************************************************
* *
* This file was automatically generated using idlc.js *
* PLEASE DO NOT EDIT!!!! *
* *
***************************************************************************/
#ifndef _name_base_H_
#define _name_base_H_
#include "../object.h"
namespace fibjs {
class Buffer_base;
class name_base : public object_base {
DECLARE_CLASS(name_base);
public:
// name_base
static result_t check(exlib::string text, bool& retVal);
static result_t sha256(Buffer_base* data, exlib::string& retVal);
public:
static void s__new(const v8::FunctionCallbackInfo<v8::Value>& args)
{
CONSTRUCT_INIT();
Isolate* isolate = Isolate::current();
isolate->m_isolate->ThrowException(
isolate->NewString("not a constructor"));
}
public:
static void s_check(const v8::FunctionCallbackInfo<v8::Value>& args);
static void s_sha256(const v8::FunctionCallbackInfo<v8::Value>& args);
};
}
#include "ifs/Buffer.h"
namespace fibjs {
inline ClassInfo& name_base::class_info()
{
static ClassData::ClassMethod s_method[] = {
{ "check", s_check, true },
{ "sha256", s_sha256, true }
};
static ClassData s_cd = {
"name", true, s__new, NULL,
ARRAYSIZE(s_method), s_method, 0, NULL, 0, NULL, 0, NULL, NULL, NULL,
&object_base::class_info()
};
static ClassInfo s_ci(s_cd);
return s_ci;
}
inline void name_base::s_check(const v8::FunctionCallbackInfo<v8::Value>& args)
{
bool vr;
METHOD_NAME("name.check");
METHOD_ENTER();
METHOD_OVER(1, 1);
ARG(exlib::string, 0);
hr = check(v0, vr);
METHOD_RETURN();
}
inline void name_base::s_sha256(const v8::FunctionCallbackInfo<v8::Value>& args)
{
exlib::string vr;
METHOD_NAME("name.sha256");
METHOD_ENTER();
METHOD_OVER(1, 1);
ARG(obj_ptr<Buffer_base>, 0);
hr = sha256(v0, vr);
METHOD_RETURN();
}
}
#endif
可以看到,通过工具我们将 IDL 快速转化为了.h
文件,其中类型的转化也与我们预期的相符,即内置类型进行相应转化,非内置类型引用对应的 class
文件。
FIBOS 官方提供了大量原生的 JavaScript 的模块和方法,你可以在 dev.fo 了解它们。通过以上的讲解你应该可以配合已经开源的 IDL 文件轻松的理解 FIBOS 中各个模块和方法的定义了。
加入我们
FIBOS 开源工作正在持续进行。您可以在 GitHub 关注我们,与我们一起完善 FIBOS。
欢迎您来为 FIBOS 贡献更多的力量。
Written by @PinelliaC