@platforma-sdk/workflow-tengo 2.9.6 → 2.9.8

package/dist/tengo/lib/ll.lib.tengo

@@ -1,319 +1,319 @@
-
+/* Low level pl API */
 
 plapi := import("plapi")
 fmt := import("fmt")
 log := import("log")
 text := import("text")
 
-
-
-
+/**
+ * Prints message to the pl log
+ */
 print := func(txt, ...args) {
-plapi.print(txt, args...)
+	plapi.print(txt, args...)
 }
 
-
-
-
-
-
+/**
+ * Panics in a template, prints the error and
+ * stops the execution of the template.
+ * After that, the controller will set errors to outputs.
+ */
 panic := func(msg, ...args) {
-txt := fmt.sprintf(msg, args...)
-plapi.print(txt)
-
+	txt := fmt.sprintf(msg, args...)
+	plapi.print(txt)
 
-plapi.setTemplateError(txt)
+	// next statement actually terminates the execution
+	plapi.setTemplateError(txt)
 }
 
-
-
-
+/**
+ * Asserts a given condition and panics if it is not met
+ */
 assert := func(condition, msg, ...args) {
-if !condition {
-panic("assertion error: condition failed: "+msg, args...)
+	if !condition {
+		panic("assertion error: condition failed: "+msg, args...)
+	}
 }
-}
-
-
-
-
-
-
 
+/**
+ * Checks whether the given object is a strict map
+ *
+ * @param obj any
+ * @return strict: bool - whether obj is a 'strict' map
+ */
 isStrict := func(obj) {
-return plapi.isStrictMap(obj)
+	return plapi.isStrictMap(obj)
 }
 
-
-
-
-
-
-
+/**
+ * Checks whether the given object is a map, a strict map or an immutable map.
+ *
+ * @param obj any
+ * @return bool whether obj is any kind of map object (map/immutable map/strict map)
+ */
 isMap := func(obj) {
-return is_map(obj) || is_immutable_map(obj) || isStrict(obj)
+	return is_map(obj) || is_immutable_map(obj) || isStrict(obj)
 }
 
-
-
-
-
-
-
-
+/**
+ * Converts 'strict' map into a normal one
+ *
+ * @param r: map|strictMap (will panic if not)
+ *
+ * @return map: std map
+ */
 fromStrict := func(r) {
-if is_map(r) {
-return r
-}
+	if is_map(r) {
+		return r
+	}
 
-if !isStrict(r) {
-panic("not a map", r)
-}
+	if !isStrict(r) {
+		panic("not a map", r)
+	}
 
-return plapi.strictToMap(r)
+	return plapi.strictToMap(r)
 }
 
-
-
-
-
-
-
+/**
+ * If input is a strict map, converts it to a normal one, otherwise returns the object as is
+ *
+ * @param r: any object (possible strict map)
+ * @return map: tengo object
+ */
 ensureNonStrict := func(r) {
-if isStrict(r) {
-return fromStrict(r)
-}
-
-return r
-}
-
-
-
-
-
-
-
-
-
-
+	if isStrict(r) {
+		return fromStrict(r)
+	}
+
+	return r
+}
+
+/**
+ * Converts map into a 'strict' map, which will panic on
+ * access to non-existing elements.
+ *
+ * @param m: map|strictMap
+ * @param recursive: boolean - convert also all child maps
+ *
+ * @return strict: strictMap
+ */
 toStrict := func(v, ...recursive) {
-if len(recursive) > 0 && recursive[0] {
-if isMap(v) {
-for k, vv in v {
-v[k] = toStrict(vv)
-}
-} else if is_array(v) {
-for i, vv in v {
-if isMap(vv) {
-v[i] = toStrict(vv)
-}
-}
-}
-
-if !isMap(v) {
-return v // for recursive transformation, accept the top-level value to be of any type (i.e. array of maps)
-}
-}
-
-if isStrict(v) {
-return v
-}
-
-if(!isMap(v)) {
-panic("toStrict(<v>): <v> is not a map", v)
-}
-return plapi.mapToStrict(v)
-}
-
-
-
-
-
-
-
-
-
+	if len(recursive) > 0 && recursive[0] {
+		if isMap(v) {
+			for k, vv in v {
+				v[k] = toStrict(vv)
+			}
+		} else if is_array(v) {
+			for i, vv in v {
+				if isMap(vv) {
+					v[i] = toStrict(vv)
+				}
+			}
+		}
+
+		if !isMap(v) {
+			return v // for recursive transformation, accept the top-level value to be of any type (i.e. array of maps)
+		}
+	}
+
+	if isStrict(v) {
+		return v
+	}
+
+	if(!isMap(v)) {
+		panic("toStrict(<v>): <v> is not a map", v)
+	}
+	return plapi.mapToStrict(v)
+}
+
+/**
+ * Safe way to check if method exists in a builtin module or a library
+ *
+ * @param module: module - builtin module or tengo library
+ * @param methodName: string - name of a method to be checked
+ *
+ * @return bool - true when method exists, false otherwise
+ */
 methodExists := func(module, methodName) {
-if isStrict(module) {
-if !is_callable(plapi.mapHasKey) {
-module = fromStrict(module)
+	if isStrict(module) {
+		if !is_callable(plapi.mapHasKey) {
+			module = fromStrict(module)
 
-} else {
-if !plapi.mapHasKey(module, methodName) {
-return false
-}
-}
-}
+		} else {
+			if !plapi.mapHasKey(module, methodName) {
+				return false
+			}
+		}
+	}
 
-method := module[methodName]
+	method := module[methodName]
 
-if is_undefined(method) {
-return false
-}
+	if is_undefined(method) {
+		return false
+	}
 
-return true
+	return true
 }
 
-
-
-
+/**
+ * Provides current API version available at runtime
+ */
 apiVersion := func() {
-if !methodExists(plapi, "apiVersion") {
-return 0 // before we introduced apiVersion
-}
+	if !methodExists(plapi, "apiVersion") {
+		return 0 // before we introduced apiVersion
+	}
 
-return plapi.apiVersion
+	return plapi.apiVersion
 }
 
-
-
-
+/**
+ * Creates a field Id struct from given resource id and field name
+ */
 fieldId := func(resourceId, fieldName) {
-return plapi.newFieldID(resourceId, fieldName)
+	return plapi.newFieldID(resourceId, fieldName)
 }
 
-
-
-
+/**
+ * Checks if <val> can be used as field ID
+ */
 isFieldId := func(val) {
-if !isStrict(val) {
-return false
-}
-v := fromStrict(val)
-return v["ResourceID"] != undefined && v["Name"] != undefined
+	if !isStrict(val) {
+		return false
+	}
+	v := fromStrict(val)
+	return v["ResourceID"] != undefined && v["Name"] != undefined
 }
 
-
-
-
+/**
+ * Converts reference ID (resource ID or field ID) to stable string representation, suitable for use as map keys
+ */
 idToString := func(referenceID) {
-if isFieldId(referenceID) {
-return fmt.sprintf("0x%X/%s", referenceID.ResourceID, referenceID.Name)
-}
-if is_int(referenceID) {
-return fmt.sprintf("0x%X", referenceID)
-}
-panic("ll.idToString: <referenceID> cannot be used as resource or field ID")
-}
-
-
-
-
+	if isFieldId(referenceID) {
+		return fmt.sprintf("0x%X/%s", referenceID.ResourceID, referenceID.Name)
+	}
+	if is_int(referenceID) {
+		return fmt.sprintf("0x%X", referenceID)
+	}
+	panic("ll.idToString: <referenceID> cannot be used as resource or field ID")
+}
+
+/**
+ * Returns current template renderer
+ */
 getCurrentTemplateRenderer := func() {
-return plapi.getTemplate()
+	return plapi.getTemplate()
 }
 
-
-
-
+/**
+ * @return isInit: bool - true when current template is initializing (executed for the first time)
+ */
 isInitializing := func() {
-return plapi.isInit
+	return plapi.isInit
 }
 
-
-
-
-
-
+/**
+ * Get the list of executors available in current Platforma installation.
+ *
+ * @return executors: []string - list of executors, say ['executor', 'docker', ...]
+ */
 getExecutorsList := func() {
-return plapi.getExecutors()
+	return plapi.getExecutors()
 }
 
-
-
-
-
-
+/**
+ * Joins path elements into a single path.
+ *
+ * @param elems: ...string - any number of elements.
+ */
 filepathJoin := func(...elems) {
-return plapi.filepathJoin(elems...)
+	return plapi.filepathJoin(elems...)
 }
 
-
-
-
-
-
-
+/**
+ * Like filepathJoin, joins elements to a single path,
+ * but can be used safely in regexps.
+ *
+ * @param elems: ...string - any number of elements.
+ */
 filepathRegexpJoin := func(...elems) {
-escapedSeparator := plapi.regexpQuoteMeta(plapi.osSeparator)
-return text.join(elems, escapedSeparator)
+	escapedSeparator := plapi.regexpQuoteMeta(plapi.osSeparator)
+	return text.join(elems, escapedSeparator)
 }
 
-
-
-
-
-
-
-
+/**
+ * Joins elements of the filepath and canonizes it, i.e.
+ * semantically resolves ../ and ./ and changes slash
+ * to a pathSeparator.
+ *
+ * @param elems: ...string - any number of elements.
+ */
 filepathCanonize := func(...elem) {
-return plapi.filepathCanonize(elem...)
+	return plapi.filepathCanonize(elem...)
 }
 
-
-
-
-
-
+/**
+ * Returns a path separator. "/" on Unix-like systems, "\\" on Windows.
+ *
+ * @return separator: string
+ */
 pathSeparator := plapi.osSeparator
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+/**
+ * Parses URL and returns a structure containing separe parts of the URL.
+ *
+ * The general form represented is:
+ *
+ *   [scheme:][//[userinfo@]host][/]path[?query][#fragment]
+ *
+ * URLs that do not start with a slash after the scheme are interpreted as:
+ *
+ *   scheme:opaque[?query][#fragment]
+ *
+ * Returns the floowing structure:
+ *
+ *   {
+ *     Scheme: string,
+ *     Host: string,
+ *     Port: number,
+ *     Path: string,
+ *     RawPath: string,
+ *     Query: string
+ *   }
+ *
+ * @param url: string with the url
+ * @return url structure: (see above)
+ */
 parseUrl := func(url) {
-return plapi.urlParse(url)
+	return plapi.urlParse(url)
 }
 
-
-
-
+/**
+ * Returns current execution context, which cab be used is a simple kv-store associated with the renderer instance.
+ */
 getCtx := func() {
-return plapi.getCtx()
+	return plapi.getCtx()
 }
 
 export toStrict({
-apiVersion: apiVersion,
-print: print,
-panic: panic,
-assert: assert,
-methodExists: methodExists,
-isStrict: isStrict,
-isMap: isMap,
-fromStrict: fromStrict,
-ensureNonStrict: ensureNonStrict,
-toStrict: toStrict,
-fieldId: fieldId,
-isFieldId: isFieldId,
-idToString: idToString,
-getCurrentTemplateRenderer: getCurrentTemplateRenderer,
-isInitializing: isInitializing,
-getExecutorsList: getExecutorsList,
-filepathJoin: filepathJoin,
-filepathRegexpJoin: filepathRegexpJoin,
-pathSeparator: pathSeparator,
-filepathCanonize: filepathCanonize,
-parseUrl: parseUrl,
-getCtx: getCtx
+	apiVersion: apiVersion,
+	print: print,
+	panic: panic,
+	assert: assert,
+	methodExists: methodExists,
+	isStrict: isStrict,
+	isMap: isMap,
+	fromStrict: fromStrict,
+	ensureNonStrict: ensureNonStrict,
+	toStrict: toStrict,
+	fieldId: fieldId,
+	isFieldId: isFieldId,
+	idToString: idToString,
+	getCurrentTemplateRenderer: getCurrentTemplateRenderer,
+	isInitializing: isInitializing,
+	getExecutorsList: getExecutorsList,
+	filepathJoin: filepathJoin,
+	filepathRegexpJoin: filepathRegexpJoin,
+	pathSeparator: pathSeparator,
+	filepathCanonize: filepathCanonize,
+	parseUrl: parseUrl,
+	getCtx: getCtx
 })