Osy#betaRun it on Osyrin: osyrin.com

Reference / Local

A command-line entry point

osy run <function> [--args-file <path|->] [--args-stdin] [--arg-file NAME=<path|->] --output json

Gives your app a command a script or a grader can call: a function that takes one case and returns one result, run with `osy run Exam --arg-file c=case.json --output json`. Stdout carries the result as JSON and nothing else; a failure is JSON on stderr with a stable code and a non-zero exit.

stable2 examples compiled by CIlocalcliauthoringtesting

Summary#

When a brief asks for an exam CLI, a command that takes a JSON test case, or a way to check the app before its screens exist, you don't need a script. Write one function that takes the case and returns the result, and the command is osy run:

osy run Exam --arg-file c=case.json --output json

It prints the function's result as JSON on stdout, and nothing else goes there. A failure prints a JSON error on stderr and exits non-zero. If the project was never compiled, or has changed since it last was, osy run compiles it first.

Signature#

osy run <function> [path] [--args-file <path|->] [--args-stdin] [--arg-file NAME=<path|->] [--arg NAME=VALUE]
                   [--output json] [--no-compile] [--as <login> --password <pw>]

Description#

What does the function look like?#

Write a function that takes one case object and returns one result object. Model both as classes, so each field has a name and a type. The function is ordinary Osy#: your tests call it, and so can a page.

class ExamCase {
  public string Question = "";
  public List<int> Numbers = [];
}

class ExamResult {
  public int Total;
  public string Verdict = "";
}

ExamResult Exam(ExamCase c) {
  var total = 0;
  foreach (var n in c.Numbers) { total = total + n; }
  return new ExamResult { Total = total, Verdict = total > 10 ? "big" : "small" };
}

A grader's case file is the case itself:

{ "question": "add them up", "numbers": [4, 5, 6] }

Field names match without regard to case, so numbers binds Numbers.

How does the case get in?#

There are two shapes. Pick the one that fits the file you are given.

the file holdsflagbinds
one value, such as a test case--arg-file c=case.jsonthe whole document to the parameter c
every argument, one property per parameter--args-file args.jsoneach property to the parameter it names, like --args-json

Use - in place of a path to read standard input. --args-stdin means --args-file -.

osy run Exam --arg-file c=case.json --output json      # the case, from a file
osy run Exam --arg-file c=- --output json < case.json  # the case, piped in
osy run Exam --args-file args.json --output json       # args.json is {"c": {…}}
cat args.json | osy run Exam --args-stdin --output json

You can layer them. One whole-arguments source (--args-json, --args-file or --args-stdin) goes first, each --arg-file goes on top of it, and each --arg goes on top of those. Standard input can only be read once, so if two flags ask for it, osy run refuses. It also refuses, rather than waiting, when a flag asks for standard input and nothing is piped in.

What comes out?#

With --output json, the result is printed on stdout as one line of JSON and the exit code is 0:

$ osy run Exam --arg-file c=case.json --output json
{"total":15,"verdict":"big"}

A number comes out as 42, a string as "hola", a list as […], and a returned row as its fields with its id. A function that returns nothing prints null. Nothing else goes to stdout: the platform starting, a compile on demand, and any notes are all written to stderr. A script can read stdout with a single JSON parse.

--json is different. It prints the whole answer (success, output, result, error, code and ranAs) as one document. Use one flag or the other, not both.

What does a failure look like?#

When the function throws or is refused, stdout stays empty, stderr gets one line of JSON, and the exit code is not zero:

$ osy run Exam --arg-file c=case.json --output json
{"error":{"code":"denied","message":"You do not have permission to create a note. — …"}}
$ echo $?
1

Branch on code. The message is written for a person and may change. The codes are stable:

codemeanswhat to do
invalidthe function refused the input (a validation error, a throw of a validation kind)the case is wrong, or the rule is
deniedthe app's security refused the caller (a rule, a policy, [Authorize])run as someone allowed: --as <login> --password <pw>
not-foundsomething the function looked up is not therecheck the ids in the case
conflictthe change clashes with the data as it isre-read and retry
unavailablea service the function called did not answertry again later
too-many-attemptssign-in attempts are being limitedwait, then try again
faultthe function failed in a way it did not declare (a bug, or a plain throw)read the message, fix the function
function-not-foundno function has that namecheck the spelling; the message lists what can run
function-not-runnablethe name is a method, a test, a constructor or a workflow stepcall a top-level function
function-ambiguoustwo kits declare that namename it in full
sign-in-refused--as did not sign incheck the login, password and --code
bad-argumentsthe flags or a case file could not be read (missing file, not JSON, nothing piped)the message names the flag
compile-failedthe compile on demand found errors (they are on stderr above the error line)fix them
not-a-projectthere is no app.osy hererun it in the project's folder, or pass its path
platform-unavailablethe local platform could not be startedthe message says why
platform-unreachablethe local platform stopped answering (exit code 2)start it again: osy launch

Does it need compiling first?#

No. osy run compiles the project first if the local platform has never compiled it, or if the source has changed since it last did. It says so on stderr:

$ osy run Exam --arg-file c=case.json --output json
The source changed since the last compile — compiling it first (`osy compile`).
{"total":15,"verdict":"big"}

osy seed <name> does the same, so on a fresh clone osy seed ExamWorld followed by osy run Exam … works with no other step. --no-compile runs whatever the platform has now.

Prove it with a test as well#

The command is for the grader. Your own check is a test that calls the same function, which osy check runs with everything else:

[Test]
void a_case_adds_its_numbers() {
  var result = Exam(new ExamCase { Question = "add them up", Numbers = [4, 5, 6] });
  Assert.Equal(15, result.Total);
  Assert.Equal("big", result.Verdict);
}

If the brief says to pass the exam cases before building screens, build this function and its command first, and run the command on a real case before you start on any page.

See also#

Running a function — osy run in full: who it runs as, entity arguments, --json.

Compiling your app — what the compile on demand runs.

[Test] / [TestFixture] — writing the test that calls the same function.

Related

Running a function

Runs one of your app's own functions from the command line — to put the app in a known state, backfill a column, or…

Compiling your app

Compiles your app's source into the app on the local platform — the inner-loop compile-and-apply. It applies additive…

[Test] / [TestFixture]

A test is an ordinary function marked [Test]. It runs against a throwaway clone of the app, so it may create rows and…