ranger-compiler 3.1.1 → 3.4.0

package/dist/lib/JinxProcess.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 
 Import "JSON.rgr"
 Import "Timers.rgr"

package/dist/lib/RangerProcess.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 
 Import "stdops.rgr"
 

package/dist/lib/Regex/RegexMatch.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 
 ; Portable regex search: pattern and haystack are strings (no /literal/ syntax).
 ; Semantics match ES6 RegExp(pattern, 'i').test(haystack) — substring search, case-insensitive.

package/dist/lib/RegexLib.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 
 ; String-based regex search (pattern as string, not /literal/ syntax).
 ;

package/dist/lib/SQL.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 
 
 systemclass SQLSchemaBuilder {

package/dist/lib/ServiceLib.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 
 operators {
     service_url _:string ( name@(noeval) ) {

package/dist/lib/Shell.rgr

@@ -0,0 +1,326 @@
+; SPDX-License-Identifier: MIT
+
+; =============================================================================
+; Shell.rgr -- running other command line programs from Ranger.
+; =============================================================================
+;
+; The compiler gives one primitive for this, `run_process_result`, which answers
+; ([exit code, stdout, stderr]) as three strings. This file is the face you
+; should actually write against: a result object instead of three strings read
+; out by index, a working directory that is remembered rather than repeated, a
+; log of every command line that was asked for, and a DRY RUN.
+;
+; The dry run is the reason a driver written on top of this can be tested at
+; all. A build that shells out to somebody else's toolchain cannot be checked on
+; a machine that does not have that toolchain -- but the DECISIONS it makes (which
+; program, which arguments, in which order, with which working directory) are
+; the part that has bugs, and those can be checked anywhere. Set `dryRun` and
+; every call records its command line and answers success without running
+; anything.
+;
+; There is no shell in the middle of any of this. The arguments are passed as a
+; vector, so a path with a space in it, an argument that starts with a dash and
+; a filename containing a `*` all arrive at the program exactly as written. The
+; `commandLine` text this file builds is for READING -- a log line, an error
+; message, a dry run transcript -- and is quoted well enough to paste back into
+; a shell, but nothing is ever executed through one.
+;
+;     def sh:Shell (new Shell)
+;     sh.cwd = "/path/to/project"
+;     def argv:[string]
+;     push argv "rev-parse"
+;     push argv "HEAD"
+;     def r:ShellResult (sh.capture("git" argv))
+;     if (r.ok()) {
+;         print (r.outText())
+;     }
+;
+; Build the argument vector rather than writing it as an inline literal: an
+; array literal handed straight to a call is lost when the call result is
+; immediately dereferenced, and a one-element one is flattened on Rust
+; (ISSUES.md #84, #85).
+;
+; =============================================================================
+
+; What a finished command answers: its exit code, whatever it printed, and the
+; command line it was asked to run (so an error can name it without the caller
+; having to keep it).
+class ShellResult {
+
+    def code:int 0
+    def out:string ""
+    def err:string ""
+    def command:string ""
+    ; True when the command was recorded but never run, which is what a dry run
+    ; does. A skipped command answers ok() -- a dry run is not a failure -- so
+    ; this is how a caller tells "it worked" from "nothing happened".
+    def skipped:boolean false
+
+    fn ok:boolean () {
+        return (code == 0)
+    }
+
+    fn failed:boolean () {
+        return (code != 0)
+    }
+
+    ; stdout without the trailing newline every command line program writes.
+    fn outText:string () {
+        return (trim out)
+    }
+
+    fn errText:string () {
+        return (trim err)
+    }
+
+    fn outLines:[string] () {
+        def body:string (trim out)
+        if ((strlen body) == 0) {
+            def empty:[string]
+            return empty
+        }
+        return (strsplit body "\n")
+    }
+
+    ; The first line of stdout, which is the whole answer for most of the
+    ; version and locate style tools a build driver asks things of.
+    fn outFirstLine:string () {
+        def lines:[string] (this.outLines())
+        if ((array_length lines) == 0) {
+            return ""
+        }
+        return (trim (itemAt lines 0))
+    }
+
+    ; What went wrong, in one line, for an error message: the exit code, the
+    ; command, and whichever of stderr/stdout has something to say.
+    fn describeFailure:string () {
+        def why:string (trim err)
+        if ((strlen why) == 0) {
+            why = (trim out)
+        }
+        def head:string ("command failed (exit " + code + "): " + command)
+        if ((strlen why) == 0) {
+            return head
+        }
+        return (head + "\n" + why)
+    }
+}
+
+; A working directory, a log, and a switch that turns every call into a record
+; of what would have run.
+class Shell {
+
+    ; The directory commands run in. "" means the one this program is in.
+    def cwd:string ""
+    ; Record commands instead of running them. Every call answers exit 0 with
+    ; no output and `skipped` set.
+    def dryRun:boolean false
+    ; Print each command line before running it.
+    def verbose:boolean false
+    ; Extra environment entries for every command this Shell runs, as
+    ; "NAME=VALUE". Merged over the ones this program was started with rather
+    ; than replacing them, so a child never loses PATH.
+    def env:[string]
+    ; Every command line this Shell was asked for, in order, dry run or not.
+    def commands:[string]
+    ; The exit code of the last command that actually ran.
+    def lastCode:int 0
+
+    Constructor () {
+    }
+
+    ; Set an environment variable for every command this Shell runs from here
+    ; on. A toolchain driver needs this more often than it looks: SDKROOT,
+    ; DEVELOPER_DIR and RANGER_LIB are all read out of the environment by the
+    ; programs they configure, and none of them can be passed as an argument.
+    fn setEnv:void (name:string value:string) {
+        def prefix:string (name + "=")
+        def kept:[string]
+        for env pair:string i {
+            if ((indexOf pair prefix) != 0) {
+                push kept pair
+            }
+        }
+        push kept (prefix + value)
+        env = kept
+    }
+
+    ; Run a program and let its output land on ours as it happens. This is what
+    ; you want for a compiler or a linker: the progress is the point, and there
+    ; is nothing to parse afterwards.
+    fn run:ShellResult (program:string argv:[string]) {
+        return (this.exec(program argv false))
+    }
+
+    ; Run a program and keep what it printed. `out` and `err` come back in the
+    ; result and nothing reaches this program's own output.
+    fn capture:ShellResult (program:string argv:[string]) {
+        return (this.exec(program argv true))
+    }
+
+    ; The trimmed stdout of a captured run, for the many tools whose entire
+    ; answer is one line. A failure answers "" rather than throwing, so a caller
+    ; that only wants the happy path does not have to unwrap anything.
+    fn text:string (program:string argv:[string]) {
+        def res:ShellResult (this.capture(program argv))
+        if (res.failed()) {
+            return ""
+        }
+        return (res.outText())
+    }
+
+    ; Did this program run and succeed? Output is captured and dropped, which is
+    ; what you want when the question is only "does this work here".
+    fn succeeds:boolean (program:string argv:[string]) {
+        def res:ShellResult (this.capture(program argv))
+        return (res.ok())
+    }
+
+    ; Where a program is on PATH, or absent when it is not installed. An
+    ; argument with a "/" in it is a path already and is answered as it stands
+    ; when the file is there -- the same rule a shell follows.
+    fn which@(optional):string (program:string) {
+        ; One optional, assigned where an answer is found and returned once.
+        ; Several `def x@(optional):string value` in branches is the obvious
+        ; way to write this, and the Rust writer turns the initialiser into
+        ; `Some(program).to_string()`, so it is written the way that survives
+        ; every target.
+        def found@(optional):string
+        def slashAt:int (indexOf program "/")
+        if (slashAt >= 0) {
+            def dirPart:string (path_dirname program)
+            def namePart:string (this.baseName(program))
+            if (file_exists dirPart namePart) {
+                found = program
+            }
+            return found
+        }
+        def pathVar@(optional):string (env_var "PATH")
+        if (null? pathVar) {
+            return found
+        }
+        def pathText:string (unwrap pathVar)
+        ; ":" everywhere but Windows, which uses ";" -- and where a ":" is also
+        ; the drive letter separator inside every entry, so the presence of a
+        ; ";" is what decides rather than the platform.
+        def sep:string ":"
+        if ((indexOf pathText ";") >= 0) {
+            sep = ";"
+        }
+        def dirs:[string] (strsplit pathText sep)
+        for dirs dir:string i {
+            if (null? found) {
+                if ((strlen dir) > 0) {
+                    if (file_exists dir program) {
+                        found = (dir + "/" + program)
+                    }
+                }
+            }
+        }
+        return found
+    }
+
+    ; Is this program installed at all? Asked before a build starts, so a
+    ; missing toolchain is one clear message instead of a confusing failure
+    ; three commands later.
+    fn isInstalled:boolean (program:string) {
+        def found@(optional):string (this.which(program))
+        if (null? found) {
+            return false
+        }
+        return true
+    }
+
+    ; The command line as a human would write it. For logs, errors and dry run
+    ; transcripts only -- nothing is executed through a shell.
+    fn commandLine:string (program:string argv:[string]) {
+        def parts:[string]
+        ; The environment first, the way a shell would take it, so a logged or
+        ; dry-run line can be pasted back into a terminal and mean the same
+        ; thing.
+        for env pair:string i {
+            def at:int (indexOf pair "=")
+            if (at > 0) {
+                def name:string (substring pair 0 at)
+                def value:string (substring pair (at + 1) (strlen pair))
+                push parts (name + "=" + (this.quote(value)))
+            }
+        }
+        push parts (this.quote(program))
+        for argv a:string i {
+            push parts (this.quote(a))
+        }
+        return (join parts " ")
+    }
+
+    ; Wrap an argument in single quotes when it holds anything a shell would
+    ; treat as syntax, so the logged line can be pasted back into a terminal.
+    fn quote:string (a:string) {
+        if ((strlen a) == 0) {
+            return "''"
+        }
+        ; Character classes as a string to look in rather than as code point
+        ; arithmetic: `charAt` answers a `char`, and what a `char` IS differs
+        ; enough between targets that the arithmetic form does not compile
+        ; everywhere. `indexOf` over a one-character substring does.
+        def safe:string "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/._-=:+,@"
+        def plain:boolean true
+        def i:int 0
+        def n:int (strlen a)
+        while (i < n) {
+            def ch:string (substring a i (i + 1))
+            if ((indexOf safe ch) < 0) {
+                plain = false
+            }
+            i = i + 1
+        }
+        if plain {
+            return a
+        }
+        ; Single quotes, because a POSIX shell re-reads nothing inside them.
+        ; A single quote in the argument itself ends the run, is escaped on its
+        ; own, and a new run is opened: the '"'"'-'\''-'"'"' dance every shell
+        ; script eventually writes by hand.
+        def q:string "'"
+        def escaped:[string] (strsplit a q)
+        def glue:string ("'" + "\\" + "'" + "'")
+        return (q + (join escaped glue) + q)
+    }
+
+    ; The last path segment, which is the program name when a caller passed a
+    ; path rather than a name.
+    fn baseName:string (p:string) {
+        def parts:[string] (strsplit p "/")
+        def cnt:int (array_length parts)
+        if (cnt == 0) {
+            return p
+        }
+        return (itemAt parts (cnt - 1))
+    }
+
+    ; Everything above lands here: log the line, honour the dry run, run it,
+    ; and turn the three strings the compiler answers into a result object.
+    fn exec:ShellResult (program:string argv:[string] capture:boolean) {
+        def line:string (this.commandLine(program argv))
+        push commands line
+        if verbose {
+            print "$ " + line
+        }
+        def res:ShellResult (new ShellResult)
+        res.command = line
+        if dryRun {
+            res.skipped = true
+            res.code = 0
+            return res
+        }
+        def raw:[string] (run_process_result program argv cwd capture env)
+        def codeText:string (itemAt raw 0)
+        def parsed@(optional):int (to_int codeText)
+        res.code = (?? parsed (0 - 1))
+        res.out = (itemAt raw 1)
+        res.err = (itemAt raw 2)
+        lastCode = res.code
+        return res
+    }
+}

package/dist/lib/Storage.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 
 ; https://developer.android.com/guide/topics/data/data-storage.html#filesInternal
 

package/dist/lib/Time.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 
 ; Legacy ES6-only host Date wrapper.
 ; For portable calendar logic use lib/IsoDateLib.rgr (ISO strings, no timezone).

package/dist/lib/Timers.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 ; operators to get time from JavaScript
 systemclass TimeIntervalID {
     es6 TimeInterval

package/dist/lib/TypedArrays.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 systemclass RUint32Array {
   es6 Uint32Array
 }

package/dist/lib/ViewLib.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 
 systemclass Bytes {
   java7 'byte[]'

package/dist/lib/WebLib.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 systemclass View {
   java7 View
   es6 View

package/dist/lib/WebServerLib.rgr

@@ -1,3 +1,5 @@
+; SPDX-License-Identifier: MIT
+
 
 ; Plan:
 ; to support: Go, PHP, Node.js