heroscript

is our small language which allows us to run parser

execute a playbook

the following will load heroscript and execute

import freeflowuniverse.crystallib.core.playbook
import freeflowuniverse.crystallib.core.playcmds

// path string
// text string
// git_url string
// git_pull bool
// git_branch string
// git_reset bool
// session  ?&base.Session      is optional
mut plbook := playbook.new(path: '....')!

//now we run all the commands as they are pre-defined in crystallib (herolib)
playcmds.run(mut plbook)!

execute a heroscript and make executable

#!/usr/bin/env hero

!!play.echo content:'this is just a test'

!!play.echo content:'this is just another test'

you can now just execute this script and hero will interprete the content

parser

are text based representatsions of parser which need to be executed

example

!!tflibrary.circlesmanager.circle_add 
    gitsource:'books'
    path:'technology/src'
    name:technology

the first one is the action, the rest are the params

import freeflowuniverse.crystallib.core.playbook




mut plbook := playbook.new(text: '....')!

way how to use for a module

import freeflowuniverse.crystallib.core.playbook

// !!hr.employee_define
//     descr:'Junior Engineer'
//     growth:'1:5,60:30' cost:'4000USD' indexation:'5%'
//     department:'engineering'


// populate the params for hr
fn (mut m BizModel) hr_actions(actions playbook.PlayBook) ! {
    mut actions2 := actions.find('hr.*,vm.start')!
    for action in actions2 {
        if action.name == 'employee_define' {
            mut name := action.params.get_default('name', '')!
            mut descr := action.params.get_default('descr', '')!
            //...
        }
    }
}

we can also use the filtersort

import freeflowuniverse.crystallib.core.playbook
import freeflowuniverse.crystallib.core.playcmds

mut plbook := playbook.new(path: '....') or { panic(err) }

// filter parser based on the criteria
//```
// string for filter is $actor:$action, ... name and globs are possible (*,?)
//
// struct FilterSortArgs
// 	 priorities  map[int]string //filter and give priority
//```
// the action_names or actor_names can be a glob in match_glob .
// see https://modules.vlang.io/index.html#string.match_glob .
// the highest priority will always be chosen . (it can be a match happens 2x)
// return  []Action
actions:=plbook.filtersort({
    5:'sshagent:*',
    10:'doctree:*',
    11:'mdbooks:*',
    12:'mdbook:*',
})!

//now process the actions if we want to do it ourselves
for a in actions{
    mut p := action.params
    mut repo := p.get_default('repo', '')!
    if p.exists('coderoot') {
        coderoot = p.get_path_create('coderoot')!
    }
}

fn new(args_ PlayBookNewArgs) !PlayBook

get a new playbook, can scan a directory or just add text

path string
text string
git_url string
git_pull bool
git_branch string
git_reset bool
session &base.Session

enum ActionState {
	init // first state
	next // will continue with next steps
	restart
	error
	done // means we don't process the next ones
}

enum ActionType {
	unknown
	dal
	sal
	wal
	macro
}

struct Action {
pub mut:
	id       int
	cid      string
	name     string
	actor    string
	priority int = 10 // 0 is highest, do 10 as default
	params   paramsparser.Params
	result   paramsparser.Params // can be used to remember outputs
	// run    bool = true // certain actions can be defined but meant to be executed directly
	actiontype ActionType = .sal
	comments   string
	done       bool // if done then no longer need to process
}

fn (action Action) str() string

fn (action Action) heroscript() string

serialize to heroscript

fn (action Action) names() []string

return list of names . the names are normalized (no special chars, lowercase, ... )

fn (action Action) hashkey() string

get hash from the action, should always be the same for the same action

struct ActionGetArgs {
pub mut:
	id         int
	actor      string
	name       string
	actiontype ActionType = .sal
}

struct ActionNewArgs {
pub mut:
	cid      string
	name     string
	actor    string
	priority int = 10 // 0 is highest, do 10 as default
	// run    bool = true // certain actions can be defined but meant to be executed directly
	actiontype ActionType
}

struct FilterSortArgs {
pub:
	priorities map[int]string // filter and give priority
}

struct FindArgs {
pub:
	filter       string
	include_done bool
}

struct HeroScriptArgs {
pub mut:
	show_done bool = true
}

struct MatchFilter {
pub mut:
	actor string
	name  string
	cid   string
}

struct PlayBook {
pub mut:
	actions    []&Action
	priorities map[int][]int // first key is the priority, the list of int's is position in list self.actions
	othertext  string        // in case there is text outside of the actions
	result     string        // if any result
	nractions  int
	done       []int // which actions did we already find/run?
	session    &base.Session
}

fn (mut plbook PlayBook) action_exists(args ActionGetArgs) bool

fn (mut plbook PlayBook) action_get(args ActionGetArgs) !&Action

fn (mut plbook PlayBook) actions_find(args ActionGetArgs) ![]&Action

Find all actions based on ActionGetArgs- If id == 0, then matches all ids; when id is specified, can only return 1.

• If actor == "", then matches all actors.
• If name == "", then matches all actions from the defined actor (if defined).
• If actiontype == .unknown, then matches all action types; when specified, filters by the action type, default .sal

fn (mut plbook PlayBook) actions_sorted(args SortArgs) ![]&Action

only return the actions which are not done yet if filtered is set, it means we only get the ones which were prioritized before

fn (mut plbook PlayBook) add(args_ PlayBookNewArgs) !

fn (mut plbook PlayBook) empty_check() !

check if playbook is empty,if not will give error, means there are actions left to be exected

fn (mut plbook PlayBook) exists_once(args FindArgs) bool

fn (mut plbook PlayBook) filtersort(args FilterSortArgs) ![]&Action

filter parser based on the criteria

 string for filter is $actor:$action, ... name and globs are possible (*,?)

 struct FilterSortArgs {
     priorities  map[int]string //filter and give priority

the action_names or actor_names can be a glob in match_glob . see https://modules.vlang.io/index.html#string.match_glob . the highest priority will always be chosen . (it can be a match happens 2x) return []Action (will only return actions which wered filtered, included in the filter-sort args)

fn (mut plbook PlayBook) find(args FindArgs) ![]&Action

filter is of form $actor.$action, ... name and globs are possible (,?) . comma separated, actor and name needs to be specified, if more than one use * glob . e.g. find("core.person_select,myactor.,green*.*")

fn (mut plbook PlayBook) find_max_one(args FindArgs) ![]&Action

fn (mut plbook PlayBook) find_one(args FindArgs) !&Action

fn (plbook PlayBook) hashkey() string

fn (mut plbook PlayBook) heroscript(args HeroScriptArgs) !string

serialize to heroscript

fn (mut plbook PlayBook) names() ![]string

return list of names . the names are normalized (no special chars, lowercase, ... )

fn (mut plbook PlayBook) params_get(filter string) !paramsparser.Params

find all relevant parser, return the params out of one . filter is of form $actor.$action, ... name and globs are possible (,?) . comma separated, actor and name needs to be specified, if more than one use * glob . e.g. find("core.person_select,myactor.,green*.*")

fn (mut plbook PlayBook) str() string

struct PlayBookNewArgs {
pub mut:
	path       string
	text       string
	git_url    string
	git_pull   bool
	git_branch string
	git_reset  bool
	prio       int = 50
	priorities map[int]string // filter and give priority, see filtersort method to know how to use
	session    ?&base.Session
}

struct SortArgs {
pub mut:
	prio_only bool // if true only show the actions which were prioritized before
}