IDL (Interface Definition Language)
Applications developed with the Sails framework include an auto-generated IDL file that contains detailed information about the application, including:
- Types: Custom types used within the program.
- Constructors: The program's constructor.
- Services: Commands and queries for all the services exposed by the program.
- Events: Events utilized within the program.
IDL versions
Sails 1.0.0 emits IDL v2. The grammar is a declarative PEG (Pest) and
supports global directives (!@sails: <version>, !@include: <path>),
local annotations (@query, @indexed, @partial, @entry_id: N),
inline service composition via extends { ... }, and pinned service
identifiers via the @<interface_id> suffix. For the full grammar, see
the IDL v2 specification.
IDL v1 (used by Sails 0.x) is preserved for compatibility with already
deployed programs and is still parsed by the legacy sails-idl-parser
crate.
Examples
Types
This example demonstrates how the custom Rust type IoTrafficLightState is represented in the corresponding IDL file.
#[sails_type]
#[derive(Clone)]
pub struct IoTrafficLightState {
pub current_light: String,
pub all_users: Vec<(ActorId, String)>,
}struct IoTrafficLightState {
current_light: String,
all_users: [(actor, String)],
}Constructors, Services and Events
The example below illustrates how a Sails program is represented in the
IDL v2 file. Note that read-only methods (&self) are annotated with
@query in the IDL output, and event payloads live inside the
service's events { ... } block.
use sails_rs::prelude::*;
#[event]
#[sails_type]
pub enum TokenEvent {
Minted { to: ActorId, value: U256 },
Transferred { from: ActorId, to: ActorId, value: U256 },
}
pub struct Token { /* ... */ }
#[service(events = TokenEvent)]
impl Token {
#[export]
pub fn mint(&mut self, to: ActorId, value: U256) {
// ...
self.emit_event(TokenEvent::Minted { to, value }).unwrap();
}
#[export]
pub fn name(&self) -> String {
// ...
String::new()
}
#[export]
pub fn balance_of(&self, account: ActorId) -> U256 {
// ...
U256::zero()
}
}
pub struct MyProgram;
#[program]
impl MyProgram {
pub fn new(name: String) -> Self {
// ...
Self
}
pub fn token(&self) -> Token {
// ...
Token { /* ... */ }
}
}!@sails: 1.0.0
service Token {
events {
Minted { to: actor, value: u256 },
Transferred { from: actor, to: actor, value: u256 },
}
functions {
Mint(to: actor, value: u256);
@query
Name() -> String;
@query
BalanceOf(account: actor) -> u256;
}
}
program MyProgram {
constructors {
New(name: String);
}
services {
Token: Token;
}
}