Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

krl-compiler

Picolab470MIT1.3.0

KRL compiler

pico-engine, krl, compiler

readme

krl-compiler

KRL to javascript compiler.

API

var compile = require('krl-compiler');

var js_string = compile(krl_string);

//it can also take an ast as input
var js_string = compile(krl_ast);

Note, this function is synchronous (since there is no I/O) and will throw errors when needed.

CLI

The compiler can be used via shell. It takes KRL code in stdin and write the javascript code to stdout.

$ npm install -g krl-compiler
$ krl-compiler < in.krl > out.js
USAGE
    krl-compiler [--verify] [--no-source-map] [--help, -h]

DESCRIPTION
    Take krl as stdin and will give js as stdout
    $ krl-compiler < in.krl > out.js

OPTIONS
    --no-source-map
        Don't append an inline source map in the output

    --verify
        On valid compilation silently exit with 0
        On failure write the error to stdout and exit with 1

    --version, -v
        output the version

    --help, -h
        Display this message

License

MIT

changelog

1.3.0 - July 29, 2023

  • Fix arithmetic. (PR #637)
  • Add DIDComm. (PR #631)
  • Add sub as an option for event:send. (PR #623)
  • Add bit operations. (PR #621)
  • Every event raised is logged. (PR #607)

1.2.0 - Jan 4, 2022

  • Update line colors in engine-UI to deemphasize parent-child relationships. Fixes issue #576
  • Fixes the typescript errors. Errors types are now treated as unknown rather than any. (PR #581)
  • Switched node-sass to sass b/c node-sass is deprecated and is a native module
  • Updated some other dependencies

1.1.1 - July 31, 2021

  • Updated Docker instructions
  • make krl-compiler more robust in the presences of compile-time errors

1.1.0 - March 31, 2021

  • add wrangler:name_changed for pico name change
  • pass thru developer-supplied attributes when creating a child pico
  • allow query to return HTML
  • support for setting cookies and redirecting from send_directive
  • UI fix to make box rule behave better for Testing tab
  • Dockerfile

1.0.10 - February 24, 2021

  • new wrangler function picoQuery (deprecating skyQuery)
  • define meta:eci inside a query as well as an event
  • CORS preflight
  • fixes issues: 543 and 546

1.0.9 - February 18, 2021

  • provide CORS headers; fixes issue 543

1.0.8 - February 16, 2021

  • make ruleset installation more robust (e.x., the URL can contain a blank)
  • fixes issues: 539 and 540

1.0.7 - February 13, 2021

  • fix klog display in the Logging tab of the developer UI

1.0.6 - February 11, 2021

  • entries for the Logging tab are now prepared in KRL code
  • fixes for issues: 536 and 533

1.0.5 - January 22, 2021

  • fix for issue: 532 add meta:rulesetConfig

1.0.3 - January 16, 2021

  • provide line/col numbers for krl-compiler errors
  • fixes for issues: 530, 527

1.0.2 - January 12, 2021

  • streamline Logging tab entries
  • fix broken subscriptions
  • fixes for issues: 529, 509, 523, 509, 492, 508, 504, 479, 478, 515
  • new route /api/flush?url=
  • new wrangler event wrangler:rulesets_need_flushing for a pico
  • schedule event ... at now working
  • remove package for pico-engine-browser no longer used
  • improved look of parent/child lines in the developer UI
  • made klog operator work in a function context

1.0.1 - January 5, 2021

  • functions can be queried requesting either HTML or plain text results (per docs)
  • event:send which allows ruleset evaulation to continue even if the ECI is not found
  • new Subscriptions tab in the developer UI and dashed magenta lines between subscription pico pairs
  • new built-in meta library to match the one in 0.52.4, with docs
  • new built-in property ctx:picoId
  • fixes for issues 488, 490, 473, 489, 486, 501, 480, 491, 500, 502, 487, 513, 512, 503, and 518
  • the io.picolabs.subscription ruleset installed in all picos
  • command line --version option for pico-engine command
  • new and simplified io.picolabs.wrangler ruleset in all picos
  • show line/col numbers for parse and compile errors
  • allow access to event attributes within functions (when called from an event context)
  • ursa module for cryptographic needs of DIDs, and its dependencies

1.0.0 - December 7, 2020

  • Ruleset versioning by url to facilitate decentralized code sharing.
  • A more pico-centric architecture that makes pico's easier to transfer between hosts.
  • Better channel policies.
  • A new UI written in React and only uses pico channels to render.
  • Built on top of pico-framework and select-when.
  • For more on v1.0.0 see the picolabs wiki

0.52.4 - February 20, 2020

  • Improvements to ruleset editor and agent tab - see more
  • Better error: <type> is not a function - see 697a386b

0.52.3 - January 15, 2020

  • Agent tab improvements - see more
  • Parse error for when no action is after if..then - see c6ba1ec2

0.52.2 - January 2, 2020

  • Ability to view and diff ruleset versions

0.52.1 - December 23, 2019

  • Fixing KRL editor to use the new parser

0.52.0 - December 20, 2019

  • New KRL parser - see 464 for change notes
  • Ability to run Pico Engine in a web browser - see pico-engine-browser
  • Allow Agent UI to remove router - see 22ff28b7

0.51.1 - August 6, 2019

  • dynamic raise statement - see 460 and 15
  • optional colon for domain:type in event expressions - see 18150b01
  • faster logging - see 4cf96486
  • UI and agent improvements

0.51.0 - July 26, 2019

  • added engine:registerRulesetFromSrc - see 456
  • added engine:doesKRLParse - see 456
  • added io.picolabs.test for testing KRL rulesets - see 456
  • added io.picolabs.ds and io.picolabs.wrangler.profile for general purpose datastore and replacement for io.picolabs.pds - see 456
  • updated io.picolabs.collection - see 456
  • use owner pico name as title - see 457
  • fixed ent:map{..} semantics to match map{..} - see 458

BREAKING CHANGES

0.50.0 - May 23, 2019

Pico Sovrin Agents are now available!

  • New KRL module: indy:*
  • New UI tab for Agent Picos
  • Added meta:rulesetLogging to indicate the ruleset logging setting. Defaults to false
  • time:now(date) can be given the number of milliseconds since the UNIX epoch.
  • Bugfix: .reduce() on a single item properly gives all 4 arguments to the reducer function.
  • Added autosend to http:* to send an event when the http response is received.
  • Updated leveldb modules.

0.49.2 - February 22, 2019

  • added additional math:* functions - see 437
  • reregister modules - see 442
  • allow dangling commas for Arrays and Maps - see 438

0.49.1 - February 8, 2019

  • logging tab now streams from log files - see 435
  • dot operator syntax for module functions - see 428

0.49.0 - November 29, 2018

  • user defined . operators i.e. a.b(c) is syntax sugar for b(a, c) - see 171
  • performance optimization for ent:v := ent:v.append(..) - see 425
  • compiler performance hint for ent:v := ent:v.put(..) - see 425
  • /api/db-dump is gone! The UI scales better now - see 424
  • enhance subscriptions tab - see 7a4ccc31
  • Add redirect directive - see ebeb516d

0.48.1 - November 9, 2018

0.48.0 - November 6, 2018

  • system started event - see 419
  • wrangler system online event - see 420
  • fix so a well-known channel is created with subscription - see 421
  • renamed event pico:intent_to_orphan to wrangler:garbage_collection - see 422

0.47.0 - September 29, 2018

  • added data = engine:exportPico(pico_id) - see 414
  • added engine:importPico(parent_id, data) setting(newPicoId) - see 415
  • added engine:setPicoStatus(pico_id, isLeaving, movedToHost) - see 414
  • added status = engine:getPicoStatus(pico_id) - see 414

BREAKING CHANGES

  • All pico-engine-core API's now use promises rather than callbacks. Including 3rd party modules and compileAndLoadRuleset.

0.46.1 - September 1, 2018

  • added math:hmac(algorithm, key, message [, encoding]) - see 413
  • added .isEmpty() - see 310
  • added .trimLeading() .trimTrailing() .trim() .startsWith(target) .endsWith(target) .contains(target) - see 405
  • Several fixes for event expressions with duplicate matches - see 406, 268, 273

0.46.0 - August 3, 2018

  • #408 Install Rulesets Validation
  • #397 Subscription cleanup

BREAKING CHANGES

  • We now only support node 8+

Notes

  • Compiled rulesets now use async+await to simulate synchronous krl code. #411

0.45.6 - June 29, 2018

  • DID login
  • started io.picolabs.cookies.
  • 367 - Array indices should be numbers not strings
  • 390 - fixing pvars index issues
  • 394 - engine:remove* should not throw up if the item was already removed
  • 396 - fixing ent var Array/Map index detection
  • 399 - engine:* functions return null when an id is not found
  • 401 - adding find and replace to krl editor

0.45.5 - May 27, 2018

0.45.4 - March 29, 2018

0.45.3 - March 19, 2018

  • Fixed event:send with empty attributes - #371
  • last should only stop evaluating the current ruleset - #366
  • 86f4c623 and 348f0c9b bug fix for subscriptions
  • 3f69e709 initial UI work for policies

0.45.2 - March 12, 2018

  • Guess the meta:host rather than defaulting to localhost - #370
  • 85f2d35e display outbound DID
  • bf3efbe0 a bit more subscriptions UI
  • c4492a81 more subscriptions UI
  • 9b9d5655 UI to propose new subscription

0.45.1 - March 8, 2018

  • Fixing string to number coercion described in #368. Fixes date compare issue #369
  • b74dabb - more consistent tab UX
  • fbcc843 - initial attempt UI to delete subscription
  • 32bab20 - fixing edge case for core.db.getStateMachine
  • e200d6c - first attempt at Subscriptions tab
  • f747228 - first cut of UI work for subscriptions

0.45.0 - February 23, 2018

  • Automated migration from io.picolabs.pico to io.picolabs.wrangler - 4c64693
  • Several fixes to select .. setting() where .. variable scope - #362, #329, #358, #359
  • Fixing type coercion behavior to be consistent especially for numbers and comparison operators - #357, #361
  • KRL editor ctrl+S binding - #356
  • schedule:remove(id) returns true/false instead of throwing an error - #363
  • KRL editor syntax highlight fix - #355
  • Removing unused syntax - #291, #293
  • Prevent ruleset dependency cycles - #260, #261
  • event:send now signals the event right away instead of waiting for the rules to complete - #364
  • UI fixes - 9647717, fa506d1, 94c1b63, a7ad98d, 97f7d5d
  • Store password as one way hash 5954b41

0.44.1 - January 15, 2018

Bug Fixes

0.44.0 - January 10, 2018

New Features

  • Making the shell log output more human friendly (see #313)
  • Storing pico-engine log file. Json encoded for easy parsing, and stored in $PICO_ENGINE_HOME/pico-engine.log (see #313)
  • Channel policies. Right now it defaults to allow-all. (see #350)
  • allow path rewriting as directed by root pico (see commit)
  • Switching to new wrangler and subscriptions. (see #351)

Upgrade notes

Because we changed io.picolabs.pico to io.picolabs.wrangler.

  • Uninstall io.picolabs.pico from the Root Pico. (open the root pico -> Rulesets tab -> click del on io.picolabs.pico).
  • For the other picos install wrangler then uninstall the old pico ruleset.

0.43.0 - December 11, 2017

Deprecations

  • event:attrs() in favor of event:attrs
  • keys:<name>() in favor of keys:<name>
  • Map key access using . operator

New Features

  • signed subscriptions
  • encrypted subscriptions
  • better type checking on engine:* function arguments
  • new KRL editor with inline compiler warnings and errors

Bug Fixes

  • select when matching falsy event attributes
  • More forgiving handling of ruleset initialization errors on startup (i.e. breaking compiler changes)
  • see issues for more

0.42.0 - November 1, 2017

BREAKING CHANGES

  • we now only support node 6+, recommended you use the LTS version (v8)

New Features

  • persistent variable indexes by using path expressions i.e. ent:foo{key}

0.41.0 - October 31, 2017

0.13.0 - September 13, 2017

Wrangler rewrite (krl/io.picolabs.pico.krl)

Wrangler provides a lot of the engine module functionality. It aims for easy, programmatically management of registering, installing, uninstalling, and listing rulesets, creation, deletion and listing of channels, as well as creation, deletion and listing of children picos. Wrangler allows you to write code to do everything that a user would us the UI for.

New Features

  • added testing for wrangler (see src/tests.js)
  • every pico now has an "admin" channel. To get it use engine:getAdminECI(pico_id)
  • engine:newPico(pico_id) now sets the parent id to pico_id creates an admin channel for you.
  • added engine:getParent(pico_id) and engine:listChildren(pico_id)
  • added engine:listInstalledRIDs(pico_id)
  • all engine:* functions that have a pico_id argument now defaults to meta:picoId
  • channel ECIs' are now sovrin DIDs.

Bug Fixes

  • sharing defaction between rulesets now return the right value
  • system rulesets (those in krl/) now are loaded by dependency ordering.
  • error handling on infinite recursion

0.12.5 - June 5, 2017

Bug Fixes

  • .put() should create nested maps, even if keys are numeric - see issue #204

0.12.4 - June 2, 2017

Bug Fixes

  • fixing race condition with schedule .. at - see issue #203

0.12.3 - June 2, 2017

Bug Fixes

  • fixing race condition with schedule .. at - see issue #203
  • better error handling for /sky/cloud/.. - see issue #32

0.12.2 - May 31, 2017

New Features

  • infix operators: like, <=>, cmp - see issue #183

Bug Fixes

  • better startup error handling - see issue #112
  • consistent casting of key paths - see issue #152
  • better as("Number") - see issue #173
  • better string concatenation rules - see issues #185 and #155
  • report error when action used in pre block - see issues #187
  • using keys:<key> in global - see issues #132

0.12.1 - May 26, 2017

New Features

  • random:uuid() - return a globally unique id (using cuid)
  • random:word() - return a random english word
  • random:integer(lower = 0, upper = 1) - return a random integer between lower and upper

  • random:number(lower = 0, upper = 1) - return a random number (float) between lower and upper

  • if event.eid == "none" or is not given, it will default to a uuid

  • event:send(event, host = null) - now when given a host string, it will send an async http sky/event request to that engine

  • better syntax for choose making the action block syntax consistent. ` ActionBlock ->

    (if <expr> then)? <Actions>

Actions -> <action> ; | every { <action 0> ; <action 1> ; ... } | sample { <action 0> ; <action 1> ; ... } | choose <expr> { <action 0> ; <action 1> ; ... }


### Bug Fixes

* `event:attr(name)` - see issue [#179](https://github.com/Picolab/pico-engine/issues/179)




# 0.12.0 - May 25, 2017

### New Features

* defaction can return values (expose values to `setting(..)`)
```krl
<name> = defaction(<params...>){
     <declaration 0>
     <declaration 1>
     ...

     <action block (i.e. anything you would put in a rule action)>

    returns <expr 0>, <expr 1>, ...
}

NOTE: returns is optional

For example

global {
    foo = defaction(){

        send_directive("foobar")

        returns 1, 2, 3
    }
}
rule bar {
    select when ...

    foo() setting(a, b, c)

    fired {
        //a = 1, b = 2, c = 3
    }
}

Another example

global {
    foo = defaction(){
        every {
            http:get(...) setting(resp)
        }
        return resp["content"].decode()["msg"]
    }
}
rule bar {
    select when ...

    foo() setting(message)
}

  • new action block type: sample This will randomly select an action to run.

    rule bar {
  select when ...

  //randomly pick one of these 3 actions to run
  sample {
      send_directive("foo")

      send_directive("bar")

      send_directive("baz")
  }
}

  • action block syntax. The semi-colons are optional.

    ActionBlock ->
    <action> ;
  | if <expr> then <action> ;
  | if <expr> then every  { <action 0> ; <action 1> ; ... }
  | if <expr> then sample { <action 0> ; <action 1> ; ... }
  | every  { <action 0> ; <action 1> ; ... }
  | sample { <action 0> ; <action 1> ; ... }
  | choose <expr> { <action 0> ; <action 1> ; ... }

BREAKING CHANGES

  • with is no longer used for named arguments. Both for functions and actions. `krl //OLD WAY foo(1, 2) with a = 3 and b = 4

//NEW WAY foo(1, 2, a = 3, b = 4)


* `with` is no longer used on `raise`/`schedule`
```krl
//OLD WAY
raise domain event "type" with foo = 1 and bar = 2

//NEW WAY
raise domain event "type" attributes {"foo": 1, "bar": 2}
  • send_directive no longer uses with it's now send_directive(name, options = {}) `krl //OLD WAY send_directive("name") with foo = x and bar = y

//NEW WAY send_directive("name", {"foo": x, "bar": y})


* No optional semi-colon after `select when ...`
```krl
//OLD WAY
select when foo bar;

//NEW WAY
select when foo bar

Bug Fixes

  • syntax ambiguities caused by with

0.11.0 - May 20, 2017

New Features

  • defaction can do anything a rule action can
    <name> = defaction(<params...>){
   <declaration 0>
   <declaration 1>
   ...
   <action block (i.e. anything you would put in a rule action)>
}

For example

chooser = defaction(val){

    baz = "hello"
    qux = "bye"

    choose val {
        asdf =>
            foo(val)
        fdsa =>
            bar(val, "ok", "done")
    }
}
  • default parameters for function and defaction (no more configure using)
foo = function(bar = 2, baz = bar + 3){
    bar + baz
}

//-or- when it gets too long
foo = function(
    bar = 2,
    baz = bar + 3,
    qux = 4,
    quux = blah(qux),
){
   ...
}


//defaction parameters work the same way as functions

BREAKING CHANGES

  • You can no longer use actions as functions
//the following are now actions and cannot be used as a function
engine:newPico
engine:removePico
engine:newChannel
engine:removeChannel
engine:registerRuleset
engine:unregisterRuleset
engine:installRuleset
engine:uninstallRuleset
event:send
schedule:remove

Bug Fixes

  • re-registering rulesets breaks the schedule order