ChangeLog
0.1.0 (2023-02-05)
Initial version.
+
+
+
+
+ 
+
+
+
+
+
+
+
+ +
Created with passion by 40Ants
+ 
+
' + _('Hide Search Matches') + '
') + .appendTo($('#searchbox')); + } + }, + + /** + * init the domain index toggle buttons + */ + initIndexTable : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + $('tr.cg-' + idnum).toggle(); + if (src.substr(-9) === 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('#searchbox .highlight-link').fadeOut(300); + $('span.highlighted').removeClass('highlighted'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this === '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + }, + + initOnKeyListeners: function() { + $(document).keydown(function(event) { + var activeElementType = document.activeElement.tagName; + // don't navigate when in search box, textarea, dropdown or button + if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT' + && activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey + && !event.shiftKey) { + switch (event.keyCode) { + case 37: // left + var prevHref = $('link[rel="prev"]').prop('href'); + if (prevHref) { + window.location.href = prevHref; + return false; + } + break; + case 39: // right + var nextHref = $('link[rel="next"]').prop('href'); + if (nextHref) { + window.location.href = nextHref; + return false; + } + break; + } + } + }); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff --git a/highlight.min.css b/highlight.min.css new file mode 100644 index 0000000..7820d7d --- /dev/null +++ b/highlight.min.css @@ -0,0 +1,7 @@ +pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*! + Theme: a11y-dark + Author: @ericwbailey + Maintainer: @ericwbailey + + Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css +*/.hljs{background:#2b2b2b;color:#f8f8f2}.hljs-comment,.hljs-quote{color:#d4d0ab}.hljs-deletion,.hljs-name,.hljs-regexp,.hljs-selector-class,.hljs-selector-id,.hljs-tag,.hljs-template-variable,.hljs-variable{color:#ffa07a}.hljs-built_in,.hljs-link,.hljs-literal,.hljs-meta,.hljs-number,.hljs-params,.hljs-type{color:#f5ab35}.hljs-attribute{color:gold}.hljs-addition,.hljs-bullet,.hljs-string,.hljs-symbol{color:#abe338}.hljs-section,.hljs-title{color:#00e0e0}.hljs-keyword,.hljs-selector-tag{color:#dcc6e0}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}@media screen and (-ms-high-contrast:active){.hljs-addition,.hljs-attribute,.hljs-built_in,.hljs-bullet,.hljs-comment,.hljs-link,.hljs-literal,.hljs-meta,.hljs-number,.hljs-params,.hljs-quote,.hljs-string,.hljs-symbol,.hljs-type{color:highlight}.hljs-keyword,.hljs-selector-tag{font-weight:700}} \ No newline at end of file diff --git a/highlight.min.js b/highlight.min.js new file mode 100644 index 0000000..d14eb0c --- /dev/null +++ b/highlight.min.js @@ -0,0 +1,466 @@ +/*! + Highlight.js v11.9.0 (git: b7ec4bfafc) + (c) 2006-2023 undefined and other contributors + License: BSD-3-Clause + */ +var hljs=function(){"use strict";function e(t){ +return t instanceof Map?t.clear=t.delete=t.set=()=>{ +throw Error("map is read-only")}:t instanceof Set&&(t.add=t.clear=t.delete=()=>{ +throw Error("set is read-only") +}),Object.freeze(t),Object.getOwnPropertyNames(t).forEach((n=>{ +const i=t[n],s=typeof i;"object"!==s&&"function"!==s||Object.isFrozen(i)||e(i) +})),t}class t{constructor(e){ +void 0===e.data&&(e.data={}),this.data=e.data,this.isMatchIgnored=!1} +ignoreMatch(){this.isMatchIgnored=!0}}function n(e){ +return e.replace(/&/g,"&").replace(//g,">").replace(/"/g,""").replace(/'/g,"'") +}function i(e,...t){const n=Object.create(null);for(const t in e)n[t]=e[t] +;return t.forEach((e=>{for(const t in e)n[t]=e[t]})),n}const s=e=>!!e.scope +;class o{constructor(e,t){ +this.buffer="",this.classPrefix=t.classPrefix,e.walk(this)}addText(e){ +this.buffer+=n(e)}openNode(e){if(!s(e))return;const t=((e,{prefix:t})=>{ +if(e.startsWith("language:"))return e.replace("language:","language-") +;if(e.includes(".")){const n=e.split(".") +;return[`${t}${n.shift()}`,...n.map(((e,t)=>`${e}${"_".repeat(t+1)}`))].join(" ") +}return`${t}${e}`})(e.scope,{prefix:this.classPrefix});this.span(t)} +closeNode(e){s(e)&&(this.buffer+="")}value(){return this.buffer}span(e){ +this.buffer+=``}}const r=(e={})=>{const t={children:[]} +;return Object.assign(t,e),t};class a{constructor(){ +this.rootNode=r(),this.stack=[this.rootNode]}get top(){ +return this.stack[this.stack.length-1]}get root(){return this.rootNode}add(e){ +this.top.children.push(e)}openNode(e){const t=r({scope:e}) +;this.add(t),this.stack.push(t)}closeNode(){ +if(this.stack.length>1)return this.stack.pop()}closeAllNodes(){ +for(;this.closeNode(););}toJSON(){return JSON.stringify(this.rootNode,null,4)} +walk(e){return this.constructor._walk(e,this.rootNode)}static _walk(e,t){ +return"string"==typeof t?e.addText(t):t.children&&(e.openNode(t), +t.children.forEach((t=>this._walk(e,t))),e.closeNode(t)),e}static _collapse(e){ +"string"!=typeof e&&e.children&&(e.children.every((e=>"string"==typeof e))?e.children=[e.children.join("")]:e.children.forEach((e=>{ +a._collapse(e)})))}}class c extends a{constructor(e){super(),this.options=e} +addText(e){""!==e&&this.add(e)}startScope(e){this.openNode(e)}endScope(){ +this.closeNode()}__addSublanguage(e,t){const n=e.root +;t&&(n.scope="language:"+t),this.add(n)}toHTML(){ +return new o(this,this.options).value()}finalize(){ +return this.closeAllNodes(),!0}}function l(e){ +return e?"string"==typeof e?e:e.source:null}function g(e){return h("(?=",e,")")} +function u(e){return h("(?:",e,")*")}function d(e){return h("(?:",e,")?")} +function h(...e){return e.map((e=>l(e))).join("")}function f(...e){const t=(e=>{ +const t=e[e.length-1] +;return"object"==typeof t&&t.constructor===Object?(e.splice(e.length-1,1),t):{} +})(e);return"("+(t.capture?"":"?:")+e.map((e=>l(e))).join("|")+")"} +function p(e){return RegExp(e.toString()+"|").exec("").length-1} +const b=/\[(?:[^\\\]]|\\.)*\]|\(\??|\\([1-9][0-9]*)|\\./ +;function m(e,{joinWith:t}){let n=0;return e.map((e=>{n+=1;const t=n +;let i=l(e),s="";for(;i.length>0;){const e=b.exec(i);if(!e){s+=i;break} +s+=i.substring(0,e.index), +i=i.substring(e.index+e[0].length),"\\"===e[0][0]&&e[1]?s+="\\"+(Number(e[1])+t):(s+=e[0], +"("===e[0]&&n++)}return s})).map((e=>`(${e})`)).join(t)} +const E="[a-zA-Z]\\w*",x="[a-zA-Z_]\\w*",w="\\b\\d+(\\.\\d+)?",y="(-?)(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)",_="\\b(0b[01]+)",O={ +begin:"\\\\[\\s\\S]",relevance:0},v={scope:"string",begin:"'",end:"'", +illegal:"\\n",contains:[O]},k={scope:"string",begin:'"',end:'"',illegal:"\\n", +contains:[O]},N=(e,t,n={})=>{const s=i({scope:"comment",begin:e,end:t, +contains:[]},n);s.contains.push({scope:"doctag", +begin:"[ ]*(?=(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):)", +end:/(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):/,excludeBegin:!0,relevance:0}) +;const o=f("I","a","is","so","us","to","at","if","in","it","on",/[A-Za-z]+['](d|ve|re|ll|t|s|n)/,/[A-Za-z]+[-][a-z]+/,/[A-Za-z][a-z]{2,}/) +;return s.contains.push({begin:h(/[ ]+/,"(",o,/[.]?[:]?([.][ ]|[ ])/,"){3}")}),s +},S=N("//","$"),M=N("/\\*","\\*/"),R=N("#","$");var j=Object.freeze({ +__proto__:null,APOS_STRING_MODE:v,BACKSLASH_ESCAPE:O,BINARY_NUMBER_MODE:{ +scope:"number",begin:_,relevance:0},BINARY_NUMBER_RE:_,COMMENT:N, +C_BLOCK_COMMENT_MODE:M,C_LINE_COMMENT_MODE:S,C_NUMBER_MODE:{scope:"number", +begin:y,relevance:0},C_NUMBER_RE:y,END_SAME_AS_BEGIN:e=>Object.assign(e,{ +"on:begin":(e,t)=>{t.data._beginMatch=e[1]},"on:end":(e,t)=>{ +t.data._beginMatch!==e[1]&&t.ignoreMatch()}}),HASH_COMMENT_MODE:R,IDENT_RE:E, +MATCH_NOTHING_RE:/\b\B/,METHOD_GUARD:{begin:"\\.\\s*"+x,relevance:0}, +NUMBER_MODE:{scope:"number",begin:w,relevance:0},NUMBER_RE:w, +PHRASAL_WORDS_MODE:{ +begin:/\b(a|an|the|are|I'm|isn't|don't|doesn't|won't|but|just|should|pretty|simply|enough|gonna|going|wtf|so|such|will|you|your|they|like|more)\b/ +},QUOTE_STRING_MODE:k,REGEXP_MODE:{scope:"regexp",begin:/\/(?=[^/\n]*\/)/, +end:/\/[gimuy]*/,contains:[O,{begin:/\[/,end:/\]/,relevance:0,contains:[O]}]}, +RE_STARTERS_RE:"!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~", +SHEBANG:(e={})=>{const t=/^#![ ]*\// +;return e.binary&&(e.begin=h(t,/.*\b/,e.binary,/\b.*/)),i({scope:"meta",begin:t, +end:/$/,relevance:0,"on:begin":(e,t)=>{0!==e.index&&t.ignoreMatch()}},e)}, +TITLE_MODE:{scope:"title",begin:E,relevance:0},UNDERSCORE_IDENT_RE:x, +UNDERSCORE_TITLE_MODE:{scope:"title",begin:x,relevance:0}});function A(e,t){ +"."===e.input[e.index-1]&&t.ignoreMatch()}function I(e,t){ +void 0!==e.className&&(e.scope=e.className,delete e.className)}function T(e,t){ +t&&e.beginKeywords&&(e.begin="\\b("+e.beginKeywords.split(" ").join("|")+")(?!\\.)(?=\\b|\\s)", +e.__beforeBegin=A,e.keywords=e.keywords||e.beginKeywords,delete e.beginKeywords, +void 0===e.relevance&&(e.relevance=0))}function L(e,t){ +Array.isArray(e.illegal)&&(e.illegal=f(...e.illegal))}function B(e,t){ +if(e.match){ +if(e.begin||e.end)throw Error("begin & end are not supported with match") +;e.begin=e.match,delete e.match}}function P(e,t){ +void 0===e.relevance&&(e.relevance=1)}const D=(e,t)=>{if(!e.beforeMatch)return +;if(e.starts)throw Error("beforeMatch cannot be used with starts") +;const n=Object.assign({},e);Object.keys(e).forEach((t=>{delete e[t] +})),e.keywords=n.keywords,e.begin=h(n.beforeMatch,g(n.begin)),e.starts={ +relevance:0,contains:[Object.assign(n,{endsParent:!0})] +},e.relevance=0,delete n.beforeMatch +},H=["of","and","for","in","not","or","if","then","parent","list","value"],C="keyword" +;function $(e,t,n=C){const i=Object.create(null) +;return"string"==typeof e?s(n,e.split(" ")):Array.isArray(e)?s(n,e):Object.keys(e).forEach((n=>{ +Object.assign(i,$(e[n],t,n))})),i;function s(e,n){ +t&&(n=n.map((e=>e.toLowerCase()))),n.forEach((t=>{const n=t.split("|") +;i[n[0]]=[e,U(n[0],n[1])]}))}}function U(e,t){ +return t?Number(t):(e=>H.includes(e.toLowerCase()))(e)?0:1}const z={},W=e=>{ +console.error(e)},X=(e,...t)=>{console.log("WARN: "+e,...t)},G=(e,t)=>{ +z[`${e}/${t}`]||(console.log(`Deprecated as of ${e}. ${t}`),z[`${e}/${t}`]=!0) +},K=Error();function F(e,t,{key:n}){let i=0;const s=e[n],o={},r={} +;for(let e=1;e<=t.length;e++)r[e+i]=s[e],o[e+i]=!0,i+=p(t[e-1]) +;e[n]=r,e[n]._emit=o,e[n]._multi=!0}function Z(e){(e=>{ +e.scope&&"object"==typeof e.scope&&null!==e.scope&&(e.beginScope=e.scope, +delete e.scope)})(e),"string"==typeof e.beginScope&&(e.beginScope={ +_wrap:e.beginScope}),"string"==typeof e.endScope&&(e.endScope={_wrap:e.endScope +}),(e=>{if(Array.isArray(e.begin)){ +if(e.skip||e.excludeBegin||e.returnBegin)throw W("skip, excludeBegin, returnBegin not compatible with beginScope: {}"), +K +;if("object"!=typeof e.beginScope||null===e.beginScope)throw W("beginScope must be object"), +K;F(e,e.begin,{key:"beginScope"}),e.begin=m(e.begin,{joinWith:""})}})(e),(e=>{ +if(Array.isArray(e.end)){ +if(e.skip||e.excludeEnd||e.returnEnd)throw W("skip, excludeEnd, returnEnd not compatible with endScope: {}"), +K +;if("object"!=typeof e.endScope||null===e.endScope)throw W("endScope must be object"), +K;F(e,e.end,{key:"endScope"}),e.end=m(e.end,{joinWith:""})}})(e)}function V(e){ +function t(t,n){ +return RegExp(l(t),"m"+(e.case_insensitive?"i":"")+(e.unicodeRegex?"u":"")+(n?"g":"")) +}class n{constructor(){ +this.matchIndexes={},this.regexes=[],this.matchAt=1,this.position=0} +addRule(e,t){ +t.position=this.position++,this.matchIndexes[this.matchAt]=t,this.regexes.push([t,e]), +this.matchAt+=p(e)+1}compile(){0===this.regexes.length&&(this.exec=()=>null) +;const e=this.regexes.map((e=>e[1]));this.matcherRe=t(m(e,{joinWith:"|" +}),!0),this.lastIndex=0}exec(e){this.matcherRe.lastIndex=this.lastIndex +;const t=this.matcherRe.exec(e);if(!t)return null +;const n=t.findIndex(((e,t)=>t>0&&void 0!==e)),i=this.matchIndexes[n] +;return t.splice(0,n),Object.assign(t,i)}}class s{constructor(){ +this.rules=[],this.multiRegexes=[], +this.count=0,this.lastIndex=0,this.regexIndex=0}getMatcher(e){ +if(this.multiRegexes[e])return this.multiRegexes[e];const t=new n +;return this.rules.slice(e).forEach((([e,n])=>t.addRule(e,n))), +t.compile(),this.multiRegexes[e]=t,t}resumingScanAtSamePosition(){ +return 0!==this.regexIndex}considerAll(){this.regexIndex=0}addRule(e,t){ +this.rules.push([e,t]),"begin"===t.type&&this.count++}exec(e){ +const t=this.getMatcher(this.regexIndex);t.lastIndex=this.lastIndex +;let n=t.exec(e) +;if(this.resumingScanAtSamePosition())if(n&&n.index===this.lastIndex);else{ +const t=this.getMatcher(0);t.lastIndex=this.lastIndex+1,n=t.exec(e)} +return n&&(this.regexIndex+=n.position+1, +this.regexIndex===this.count&&this.considerAll()),n}} +if(e.compilerExtensions||(e.compilerExtensions=[]), +e.contains&&e.contains.includes("self"))throw Error("ERR: contains `self` is not supported at the top-level of a language. See documentation.") +;return e.classNameAliases=i(e.classNameAliases||{}),function n(o,r){const a=o +;if(o.isCompiled)return a +;[I,B,Z,D].forEach((e=>e(o,r))),e.compilerExtensions.forEach((e=>e(o,r))), +o.__beforeBegin=null,[T,L,P].forEach((e=>e(o,r))),o.isCompiled=!0;let c=null +;return"object"==typeof o.keywords&&o.keywords.$pattern&&(o.keywords=Object.assign({},o.keywords), +c=o.keywords.$pattern, +delete o.keywords.$pattern),c=c||/\w+/,o.keywords&&(o.keywords=$(o.keywords,e.case_insensitive)), +a.keywordPatternRe=t(c,!0), +r&&(o.begin||(o.begin=/\B|\b/),a.beginRe=t(a.begin),o.end||o.endsWithParent||(o.end=/\B|\b/), +o.end&&(a.endRe=t(a.end)), +a.terminatorEnd=l(a.end)||"",o.endsWithParent&&r.terminatorEnd&&(a.terminatorEnd+=(o.end?"|":"")+r.terminatorEnd)), +o.illegal&&(a.illegalRe=t(o.illegal)), +o.contains||(o.contains=[]),o.contains=[].concat(...o.contains.map((e=>(e=>(e.variants&&!e.cachedVariants&&(e.cachedVariants=e.variants.map((t=>i(e,{ +variants:null},t)))),e.cachedVariants?e.cachedVariants:q(e)?i(e,{ +starts:e.starts?i(e.starts):null +}):Object.isFrozen(e)?i(e):e))("self"===e?o:e)))),o.contains.forEach((e=>{n(e,a) +})),o.starts&&n(o.starts,r),a.matcher=(e=>{const t=new s +;return e.contains.forEach((e=>t.addRule(e.begin,{rule:e,type:"begin" +}))),e.terminatorEnd&&t.addRule(e.terminatorEnd,{type:"end" +}),e.illegal&&t.addRule(e.illegal,{type:"illegal"}),t})(a),a}(e)}function q(e){ +return!!e&&(e.endsWithParent||q(e.starts))}class J extends Error{ +constructor(e,t){super(e),this.name="HTMLInjectionError",this.html=t}} +const Y=n,Q=i,ee=Symbol("nomatch"),te=n=>{ +const i=Object.create(null),s=Object.create(null),o=[];let r=!0 +;const a="Could not find the language '{}', did you forget to load/include a language module?",l={ +disableAutodetect:!0,name:"Plain text",contains:[]};let p={ +ignoreUnescapedHTML:!1,throwUnescapedHTML:!1,noHighlightRe:/^(no-?highlight)$/i, +languageDetectRe:/\blang(?:uage)?-([\w-]+)\b/i,classPrefix:"hljs-", +cssSelector:"pre code",languages:null,__emitter:c};function b(e){ +return p.noHighlightRe.test(e)}function m(e,t,n){let i="",s="" +;"object"==typeof t?(i=e, +n=t.ignoreIllegals,s=t.language):(G("10.7.0","highlight(lang, code, ...args) has been deprecated."), +G("10.7.0","Please use highlight(code, options) instead.\nhttps://github.com/highlightjs/highlight.js/issues/2277"), +s=e,i=t),void 0===n&&(n=!0);const o={code:i,language:s};N("before:highlight",o) +;const r=o.result?o.result:E(o.language,o.code,n) +;return r.code=o.code,N("after:highlight",r),r}function E(e,n,s,o){ +const c=Object.create(null);function l(){if(!N.keywords)return void M.addText(R) +;let e=0;N.keywordPatternRe.lastIndex=0;let t=N.keywordPatternRe.exec(R),n="" +;for(;t;){n+=R.substring(e,t.index) +;const s=_.case_insensitive?t[0].toLowerCase():t[0],o=(i=s,N.keywords[i]);if(o){ +const[e,i]=o +;if(M.addText(n),n="",c[s]=(c[s]||0)+1,c[s]<=7&&(j+=i),e.startsWith("_"))n+=t[0];else{ +const n=_.classNameAliases[e]||e;u(t[0],n)}}else n+=t[0] +;e=N.keywordPatternRe.lastIndex,t=N.keywordPatternRe.exec(R)}var i +;n+=R.substring(e),M.addText(n)}function g(){null!=N.subLanguage?(()=>{ +if(""===R)return;let e=null;if("string"==typeof N.subLanguage){ +if(!i[N.subLanguage])return void M.addText(R) +;e=E(N.subLanguage,R,!0,S[N.subLanguage]),S[N.subLanguage]=e._top +}else e=x(R,N.subLanguage.length?N.subLanguage:null) +;N.relevance>0&&(j+=e.relevance),M.__addSublanguage(e._emitter,e.language) +})():l(),R=""}function u(e,t){ +""!==e&&(M.startScope(t),M.addText(e),M.endScope())}function d(e,t){let n=1 +;const i=t.length-1;for(;n<=i;){if(!e._emit[n]){n++;continue} +const i=_.classNameAliases[e[n]]||e[n],s=t[n];i?u(s,i):(R=s,l(),R=""),n++}} +function h(e,t){ +return e.scope&&"string"==typeof e.scope&&M.openNode(_.classNameAliases[e.scope]||e.scope), +e.beginScope&&(e.beginScope._wrap?(u(R,_.classNameAliases[e.beginScope._wrap]||e.beginScope._wrap), +R=""):e.beginScope._multi&&(d(e.beginScope,t),R="")),N=Object.create(e,{parent:{ +value:N}}),N}function f(e,n,i){let s=((e,t)=>{const n=e&&e.exec(t) +;return n&&0===n.index})(e.endRe,i);if(s){if(e["on:end"]){const i=new t(e) +;e["on:end"](n,i),i.isMatchIgnored&&(s=!1)}if(s){ +for(;e.endsParent&&e.parent;)e=e.parent;return e}} +if(e.endsWithParent)return f(e.parent,n,i)}function b(e){ +return 0===N.matcher.regexIndex?(R+=e[0],1):(T=!0,0)}function m(e){ +const t=e[0],i=n.substring(e.index),s=f(N,e,i);if(!s)return ee;const o=N +;N.endScope&&N.endScope._wrap?(g(), +u(t,N.endScope._wrap)):N.endScope&&N.endScope._multi?(g(), +d(N.endScope,e)):o.skip?R+=t:(o.returnEnd||o.excludeEnd||(R+=t), +g(),o.excludeEnd&&(R=t));do{ +N.scope&&M.closeNode(),N.skip||N.subLanguage||(j+=N.relevance),N=N.parent +}while(N!==s.parent);return s.starts&&h(s.starts,e),o.returnEnd?0:t.length} +let w={};function y(i,o){const a=o&&o[0];if(R+=i,null==a)return g(),0 +;if("begin"===w.type&&"end"===o.type&&w.index===o.index&&""===a){ +if(R+=n.slice(o.index,o.index+1),!r){const t=Error(`0 width match regex (${e})`) +;throw t.languageName=e,t.badRule=w.rule,t}return 1} +if(w=o,"begin"===o.type)return(e=>{ +const n=e[0],i=e.rule,s=new t(i),o=[i.__beforeBegin,i["on:begin"]] +;for(const t of o)if(t&&(t(e,s),s.isMatchIgnored))return b(n) +;return i.skip?R+=n:(i.excludeBegin&&(R+=n), +g(),i.returnBegin||i.excludeBegin||(R=n)),h(i,e),i.returnBegin?0:n.length})(o) +;if("illegal"===o.type&&!s){ +const e=Error('Illegal lexeme "'+a+'" for mode "'+(N.scope||"
+
+ 
This is a small utility, which can generate GitHub workflows for Common Lisp +projects.
It generates workflow for running tests and building docs. These workflows
+use 40ants/run-tests and 40ants/build-docs
+actions and SBLint to check code for compilation errors.
Description: A tool simplify continuous deployment for Common Lisp projects.
Licence: BSD
Author: Alexander Artemenko
Homepage: https://40ants.com/ci/
Source control: GIT
Depends on: alexandria, serapeum, str, yason
This system hides all entrails related to caching.
Includes a few ready to use job types.
Custom job types can be defined and distributed as separate ASDF systems.
You don't have to write YAML anymore!
This system allows you to define workflows in the lisp code. The best way is to make these
+definitions a part of your ASDF system. This way 40ants-ci (1 2) will be able to
+automatically understand for which system it builds a workflow.
Each workflow consists of jobs and each job is a number of steps.
There are three predefine types of jobs and you can create your own. Predefined jobs
+allows to reuse steps in multiple CL libraries.
In next examples, I'll presume you are writing code in a file which is the part
+of the package inferred ASDF system EXAMPLE/CI. A file should have the following header:
(defpackage #:example/ci
+ (:use #:cl)
+ (:import-from #:40ants-ci/workflow
+ #:defworkflow)
+ (:import-from #:40ants-ci/jobs/linter)
+ (:import-from #:40ants-ci/jobs/run-tests)
+ (:import-from #:40ants-ci/jobs/docs))This job is automates git tag placement on the commit where you have changed the ChangeLog.md.
This can be a useful to automate package deployment and releases. You update the changelog, +a job pushes a new git tag and the next action triggers on this tag and build a release.
Or you if you publish your library at Quicklisp distribution, then you can change
+it's source type to the latest-github-tag to provide more stable releases to your
+users. This way you commits into master will be ignored until you change the changelog and
+git tag will be pushed. Here is an example how to setup this kind of quicklisp project source.
(defworkflow release
+ :on-push-to "master"
+ :jobs ((40ants-ci/jobs/autotag:autotag)))Creates a job which will run autotagger to create a new git tag for release.
This type of the job created a git tag when finds a new tag in specified file.
The simplest job type is linter. It loads a
(defworkflow linter
+ :on-pull-request t
+ :jobs ((40ants-ci/jobs/linter:linter)))When you'll hit C-c C-c on this definition,
+it will generate .github/workflows/linter.yml with following content:
{
+ "name": "LINTER",
+ "on": {
+ "pull_request": null
+ },
+ "jobs": {
+ "linter": {
+ "runs-on": "ubuntu-latest",
+ "env": {
+ "OS": "ubuntu-latest",
+ "QUICKLISP_DIST": "quicklisp",
+ "LISP": "sbcl-bin"
+ },
+ "steps": [
+ {
+ "name": "Checkout Code",
+ "uses": "actions/checkout@v4"
+ },
+ {
+ "name": "Setup Common Lisp Environment",
+ "uses": "40ants/setup-lisp@v4",
+ "with": {
+ "asdf-system": "example"
+ }
+ },
+ {
+ "name": "Install SBLint",
+ "run": "qlot exec ros install cxxxr/sblint",
+ "shell": "bash"
+ },
+ {
+ "name": "Run Linter",
+ "run": "qlot exec sblint example.asd",
+ "shell": "bash"
+ }
+ ]
+ }
+ }
+}Here you can see, a few steps in the job:
Checkout the code.
Install Roswell & Qlot using 40ants/setup-lisp action.
Install SBLint.
Run linter for example.asd.
Another interesting thing is that this workflow automatically uses ubuntu-latest OS,
+Quicklisp and sbcl-bin Lisp implementation. Later I'll show you how to redefine these settings.
This job is similar to linter, but instead of SBLint it runs
+Lisp Critic.
Lisp Critic is a program which advices how to make you Common Lisp code more +idiomatic, readable and performant. Also, sometimes it might catch logical +errors in the code.
Here is how you can add this job type in your workflow:
(defworkflow ci
+ :on-pull-request t
+ :jobs ((40ants-ci/jobs/critic:critic)))Also, you might combine this job together with others, for example, +with linter:
(defworkflow ci
+ :on-pull-request t
+ :jobs ((40ants-ci/jobs/linter:linter)
+ (40ants-ci/jobs/critic:critic)))and they will be executed in parallel. See docs on 40ants-ci/jobs/critic:critic function
+to learn about supported arguments.
Another interesting job type is 40ants-ci/jobs/run-tests:run-tests (1 2).
When using this job type, make sure, your system
+runs tests on (ASDF:TEST-SYSTEM :system-name) call
+and signals error if something went wrong.
+(defworkflow ci
+ :on-push-to "master"
+ :by-cron "0 10 * * 1"
+ :on-pull-request t
+ :jobs ((40ants-ci/jobs/run-tests:run-tests
+ :coverage t)))
+Here I've added a few options to the workflow:
by-cron - sets a schedule.
on-push-to - defines a branch or branches to track.
It will generate .github/workflows/ci.yml with following content:
{
+ "name": "CI",
+ "on": {
+ "push": {
+ "branches": [
+ "master"
+ ]
+ },
+ "pull_request": null,
+ "schedule": [
+ {
+ "cron": "0 10 * * 1"
+ }
+ ]
+ },
+ "jobs": {
+
+ "run-tests": {
+ "runs-on": "ubuntu-latest",
+ "env": {
+ "OS": "ubuntu-latest",
+ "QUICKLISP_DIST": "quicklisp",
+ "LISP": "sbcl-bin"
+ },
+ "steps": [
+ {
+ "name": "Checkout Code",
+ "uses": "actions/checkout@v4"
+ },
+ {
+ "name": "Setup Common Lisp Environment",
+ "uses": "40ants/setup-lisp@v4",
+ "with": {
+ "asdf-system": "example"
+ }
+ },
+ {
+ "name": "Run Tests",
+ "uses": "40ants/run-tests@v2",
+ "with": {
+ "asdf-system": "example",
+ "coveralls-token": "${{ secrets.github_token }}"
+ }
+ }
+ ]
+ }
+ }
+}
+The result is similar to the workflow generated for Linter, +but uses 40ants/setup-lisp action +at the final step.
Also, I've passed an option :coverage t to the job. Thus coverage
+report will be uploaded to Coveralls.io automatically.
Lisp has many implementations and can be used on multiple platforms. Thus
+it is a good idea to test our software on many combinations of OS and lisp
+implementations. Workflow generator makes this very easy.
Here is an example of workflow definition with three dimentional matrix.
+It not only tests a library under different lisps and OS, but also checks
+if it works with the latest Quicklisp and Ultralisp distributions:
(defworkflow ci
+ :on-pull-request t
+ :jobs ((run-tests
+ :os ("ubuntu-latest"
+ "macos-latest")
+ :quicklisp ("quicklisp"
+ "ultralisp")
+ :lisp ("sbcl-bin"
+ "ccl-bin"
+ "allegro"
+ "clisp"
+ "cmucl")
+ :exclude (;; Seems allegro is does not support 64bit OSX.
+ ;; Unable to install it using Roswell:
+ ;; alisp is not executable. Missing 32bit glibc?
+ (:os "macos-latest" :lisp "allegro")))))Besides a build matrix, you might specify a multiple jobs of the same type, +but with different parameters:
(defworkflow ci
+ :on-push-to "master"
+ :on-pull-request t
+ :jobs ((run-tests
+ :lisp "sbcl-bin")
+ (run-tests
+ :lisp "ccl-bin")
+ (run-tests
+ :lisp "allegro")))This will generate a workflow with three jobs: "run-tests", "run-tests-2" and "run-tests-3".
Meaningful names might be specified as well:
(defworkflow ci
+ :on-push-to "master"
+ :on-pull-request t
+ :jobs ((run-tests
+ :name "test-on-sbcl"
+ :lisp "sbcl-bin")
+ (run-tests
+ :name "test-on-ccl"
+ :lisp "ccl-bin")
+ (run-tests
+ :name "test-on-allegro"
+ :lisp "allegro")))Here is how these jobs will look like in the GitHub interface:
Third predefined job type is 40ants-ci/jobs/docs:build-docs (1 2).
+It uses 40ants/build-docs
+action and will work only if your ASDF system uses a documentation builder supported by
+40ants/docs-builder.
To build docs on every push to master, just use this code:
+(defworkflow docs
+ :on-push-to "master"
+ :jobs ((40ants-ci/jobs/docs:build-docs)))
+It will generate .github/workflows/docs.yml with following content:
+{
+ "name": "DOCS",
+ "on": {
+ "push": {
+ "branches": [
+ "master"
+ ]
+ }
+ },
+ "jobs": {
+ "build-docs": {
+ "runs-on": "ubuntu-latest",
+ "env": {
+ "OS": "ubuntu-latest",
+ "QUICKLISP_DIST": "quicklisp",
+ "LISP": "sbcl-bin"
+ },
+ "steps": [
+ {
+ "name": "Checkout Code",
+ "uses": "actions/checkout@v4"
+ },
+ {
+ "name": "Setup Common Lisp Environment",
+ "uses": "40ants/setup-lisp@v4",
+ "with": {
+ "asdf-system": "example",
+ "qlfile-template": ""
+ }
+ },
+ {
+ "name": "Build Docs",
+ "uses": "40ants/build-docs@v1",
+ "with": {
+ "asdf-system": "example"
+ }
+ }
+ ]
+ }
+ }
+}
+To significantly speed up our tests, we can cache installed Roswell, +Qlot and Common Lisp fasl files.
To accomplish this task, you don't need to dig into GitHub's docs anymore!
+Just add one line :cache t to your workflow definition:
(defworkflow docs
+ :on-push-to "master"
+ :cache t
+ :jobs ((40ants-ci/jobs/docs:build-docs)))Here is the diff of the generated workflow file. It shows steps, added automatically:
modified .github/workflows/docs.yml
+@@ -20,13 +20,40 @@
+ "name": "Checkout Code",
+ "uses": "actions/checkout@v4"
+ },
++ {
++ "name": "Grant All Perms to Make Cache Restoring Possible",
++ "run": "sudo mkdir -p /usr/local/etc/roswell\n sudo chown \"${USER}\" /usr/local/etc/roswell\n # Here the ros binary will be restored:\n sudo chown \"${USER}\" /usr/local/bin",
++ "shell": "bash"
++ },
++ {
++ "name": "Get Current Month",
++ "id": "current-month",
++ "run": "echo \"::set-output name=value::$(date -u \"+%Y-%m\")\"",
++ "shell": "bash"
++ },
++ {
++ "name": "Cache Roswell Setup",
++ "id": "cache",
++ "uses": "actions/cache@v3",
++ "with": {
++ "path": "qlfile\n qlfile.lock\n /usr/local/bin/ros\n ~/.cache/common-lisp/\n ~/.roswell\n /usr/local/etc/roswell\n .qlot",
++ "key": "${{ steps.current-month.outputs.value }}-${{ env.cache-name }}-ubuntu-latest-quicklisp-sbcl-bin-${{ hashFiles('qlfile.lock') }}"
++ }
++ },
++ {
++ "name": "Restore Path To Cached Files",
++ "run": "echo $HOME/.roswell/bin >> $GITHUB_PATH\n echo .qlot/bin >> $GITHUB_PATH",
++ "shell": "bash",
++ "if": "steps.cache.outputs.cache-hit == 'true'"
++ },
+ {
+ "name": "Setup Common Lisp Environment",
+ "uses": "40ants/setup-lisp@v4",
+ "with": {
+ "asdf-system": "40ants-ci",
+ "qlfile-template": ""
+- }
++ },
++ "if": "steps.cache.outputs.cache-hit != 'true'"
+ },
+ {TODO: I have to write a few chapters with details on additional job's parameters
+and a way how to create new job types.
But for now, I want to show a small example, how to define a workflow with a +job which takes care about lisp installation and then calls a custom step:
(defworkflow ci
+ :on-push-to "master"
+ :by-cron "0 10 * * 1"
+ :on-pull-request t
+ :cache t
+ :jobs ((40ants-ci/jobs/lisp-job:lisp-job :name "check-ros-config"
+ :lisp "ccl-bin"
+ :steps ((40ants-ci/steps/sh:sh "Show Roswell Config"
+ "ros config")))))Here we are using the class 40ants-ci/jobs/lisp-job:lisp-job which is base for most classes in this ASDF system
+and pass a custom 40ants-ci/steps/sh:sh (1 2) step to it. This step will be called after the repostory checkout and CCL-BIN lisp installation.
+so, thus when this step will run ros config command, it will output something like that:
asdf.version=3.3.5.3
+ccl-bin.version=1.12.2
+setup.time=3918000017
+sbcl-bin.version=2.4.1
+default.lisp=ccl-bin
+
+Possible subcommands:
+set
+showPay attention to the NAME argument of 40ants-ci/jobs/lisp-job:lisp-job class. If you omit it, then default "lisp-job" name will be used.
Generates GitHub workflow for given ASDF system.
This function searches workflow definitions in all packages
+of the given ASDF system.
If PATH argument is not given, workflow files will be written
+to .github/workflow/ relarive to the SYSTEM.
When workflow is generated for ASDF system, this variable will contain a primary ASDF system.
This type of the job created a git tag when finds a new tag in specified file.
Readers
File where to search for version numbers.
Regexp used to extract version numbers.
Tag prefix.
Auth token pattern.
Creates a job which will run autotagger to create a new git tag for release.
Readers
Critic can validate more than one system, but for the base class we need provide only one.
A list strigns with names of critiques to ignore.
Creates a job which will run Lisp Critic for given ASDF systems.
If argument ASDF-SYSTEMS is NIL, it will use ASDF system
+to which current lisp file is belong.
You may also provide ASDF-VERSION argument. It should be
+a string. By default, the latest ASDF version will be used.
Builds documentation and uploads it to GitHub using "40ants/build-docs" github action.
Readers
Creates a job of class build-docs.
Readers
A list of plists denoting matrix combinations to be excluded.
This slot holds steps given as a STEPS argument to a job constructor. Depending on a job class, it might add additional steps around these explicit steps.
An alist of environment variables and their values to be added on job level. Values are evaluated in runtime.
If this name was not given in constructor, then name will be lowercased name of the job class.
A plist of permissions need for running the job.
These permissions will be bound to secrets.GITHUB_TOKEN variable.
+Use default-initargs to override permissions in subclasses:
(:default-initargs
+ :permissions '(:content "write"))Should return an alist with mapping from string to string where keys are scopes and values are permission names. Default method generates this alist from the plist of job's "permissions" slot.
Readers
Linter can validate more than one system, but for the base class we need provide only one.
Linter will check for missing or unused imports of package-inferred systems.
Creates a job which will run SBLint for given ASDF systems.
If no ASD files given, it will use all ASD files from
+the current ASDF system.
This job checkouts the sources, installs Roswell and Qlot. Also, it caches results between runs.
Readers
ASDF version to use when setting up Lisp environment. If NIL, then the latest will be used.
Qlot version to use when setting up Lisp environment. If NIL, then will be used version, pinned in setup-lisp github action.
Roswell version to use when setting up Lisp environment. If NIL, then will be used version, pinned in setup-lisp github action.
This job test runs tests for a given ASDF system.
Readers
Creates a job step of class run-tests.
Readers
A plist to be passed as "with" dictionary to the action.
Readers
Returns a string with a bash script where some parts are grouped.
In this example we have 3 sections:
(sections
+ ("Help Argument"
+ "qlot exec cl-info --help")
+ ("Version Argument"
+ "qlot exec cl-info --version")
+ ("Lisp Systems Info"
+ "qlot exec cl-info"
+ "qlot exec cl-info cl-info defmain"))It will be compiled into:
echo ::group::Help Argument
+qlot exec cl-info --help
+echo ::endgroup::
+echo ::group::Version Argument
+qlot exec cl-info --version
+echo ::endgroup::
+echo ::group::Lisp Systems Info
+qlot exec cl-info
+qlot exec cl-info cl-info defmain
+echo ::endgroup::Readers
An alist of environment variables.
Returns a list of packages created by ASDF system.
Default implementation returns a package having the same name as a system +and all packages matched to package-inferred subsystems:
CL-USER> (docs-builder/utils:system-packages :docs-builder)
+(#<PACKAGE "DOCS-BUILDER">
+ #<PACKAGE "DOCS-BUILDER/UTILS">
+ #<PACKAGE "DOCS-BUILDER/GUESSER">
+ #<PACKAGE "DOCS-BUILDER/BUILDERS/GENEVA/GUESSER">
+ #<PACKAGE "DOCS-BUILDER/BUILDER">
+ #<PACKAGE "DOCS-BUILDER/BUILDERS/MGL-PAX/GUESSER">
+ #<PACKAGE "DOCS-BUILDER/DOCS">
+ #<PACKAGE "DOCS-BUILDER/BUILDERS/MGL-PAX/BUILDER">)Test wheather LIST argument is a properly formed alist.
In this library, alist has always a string as a key.
+Because we need them to have this form to serialize
+to JSON propertly.
(alistp '(("cron" . "0 10 * * 1"))) -> T
+(alistp '((("cron" . "0 10 * * 1")))) -> NIL
Removes common leading whitespace from each string.
A few examples:
(dedent "Hello
+ World
+ and all Lispers!")
+
+"Hello
+World
+and all Lispers!"(dedent "
+ Hello
+ World
+ and all Lispers!")
+
+"Hello
+World
+and all Lispers!"(dedent "This is a code:
+
+ (symbol-name :hello-world)
+
+ it will output HELLO-WORLD.")
+
+"This is a code:
+
+ (symbol-name :hello-world)
+
+it will output HELLO-WORLD."Make an alist from a plist PLIST.
By default, transforms keys to lowercased strings
Test wheather LIST is a properly formed plist.
Test wheather LIST contains exactly 1 element.
When workflow is generated for ASDF system, this variable will contain a primary ASDF system.
Workflow will set this variable when preparing the data or YAML generation.
Created with passion by 40Ants
+
+
').appendTo(this.out); + this.output = $('