Skip to content

Latest commit

 

History

History
184 lines (143 loc) · 5.63 KB

cut.md

File metadata and controls

184 lines (143 loc) · 5.63 KB
Raw

The Cut

From Wikipedia:

Traditionally, the "director's cut" is not, by definition, the director's ideal or preferred cut. The editing process of a film is broken into stages:

  • First is the assembly/rough cut, where all selected takes are put together in the order in which they should appear in the film.
  • Next, the editor's cut is reduced from the rough cut; the editor may be guided by his own tastes or following notes from the director or producers.
  • Eventually is the final cut, which actually gets released or broadcast.
  • In between the editor's cut and the final cut can come any number of fine cuts, including the director's cut.

Register for seeding template data

A Cut allows data to be stored and propagated to Frames in a Reel sequence using instructions held in a Frame's Cut Instruction Set.

Cut File - a JSON file starting with a Reel name and ending with the suffix .cut.json.

  • Ex: For a Reel with a name of product, the associated Cut file will be named product.cut.json.
  • Holds a single Cut Register object.

Cut Register - The JSON object stored in the Cut file.

  • Is an associative array containing valid JSON objects.
  • Holds Cut Variables and their corresponding values stored in a series of key/value pairs.

{
  "FIRST_NAME": "Primus",
  "RESPONSE": "ALRIGHT"
}

Listing 1: The Cut file usr.cut.json with a Cut Register holding the string values for the Cut Variables FIRST_NAME and RESPONSE.

Cut Variable- a named variable that references a single string value in the Cut Register.

  • Cut Variables referenced in a Frame's request/response bodies must be :
    • prepended with a left delimiter - ${
    • and terminated with a right delimiter - }.
  • Ex: The Cut Variable USER_ID found in the Cut Register will be referenced as-is in a Frame's Cut instruction set and as ${USER_ID} in the request/response objects.
  • Mimics shell parameter expansion syntax.
  • The left delimiter can be escaped by placing two backslashes before the dollar sign: \\$.

{
  "protocol": "HTTP",
  "cut": {
    "from": [
      "USER_ID"
    ]
  },
  "request": {
    "uri": "POST /logout/${USER_ID}"
  },
  "response": {
    "body": "User:${USER_ID} logged out",
    "status": 200
  }
}

Listing 2: An example Frame that logs out a user using a Cut Variable to build the request URI.

Cut operation - A procedure that uses instructions held in a Frame's Cut Instruction Set to read and write Cut Variables to the Cut Register.

  • Reads "from" and writes "to" the Cut Register .

Read operation - A Cut operation that uses a read instruction to insert a Cut Variable into a Frame's request/response objects.

  • Uses the read instructions held in a Cut Instruction Set to populate Cut Variable references found in a Frame.
  • Executed before a Frame' request payload is sent.

Write operation - A Cut operation that takes a Frame's Write instruction object and creates or reassigns the matching key value found in the Cut Register.

  • Uses a syntax similar to jq filters for JSON traversal.
  • Executed after a Frame's request payload is sent.
  • Operates on variable references inside response object only.

{
  "protocol": "HTTP",
  "request": {
    "uri": "POST /logout/\\${USER_ID}"
  },
  "response": {
    "status": 200
  }
}

Listing 3: When interpreting the Frame file above, the request uri value will be processed as "POST /logout/${USER_ID}" due to the escaped left delimiter.

Cut Errors

Register Parse Error - returned when:

  • A Cut Register key maps to a non-string data type.

Frame Parse Error - returned when:

  • A Frame string contains a dollar sign and open brace ${ that is not later followed by a matching close brace }.
  • A Frame's request/response objects hold Cut Variable references not found in the Cut Instruction Set.
  • The "from" key in a Frame instruction set does not map to an array of strings.
  • The "to" key in a Frame instruction set does not map to an associative array of strings.

General Instruction Error - returned when:

  • A Cut instruction fails to return a string holding the equivalent Cut Variable reference.

Read Instruction Error - returned when:

  • A Frame's read instruction holds a Cut Variable reference that is missing from the Frame's request/response objects.
  • The variable referenced in a Frame's Cut instruction is not found in the Cut Register.

Write Instruction Error - returned when:

  • A Write operation attempts to handle a non-string data type.
  • A Write instruction returns multiple references of the same Cut Variable.

{
 "protocol": "HTTP",
 "request": {
   "body": {
     "full_name": "Primus ${LAST_NAME" // Frame Parse Error
   },
   "uri": "GET /email/by_name"
 },
 "response": {
   "body": {
     "email": "[email protected]"
   },
   "status": 200
 }
}

Listing 4: While the object above is valid JSON, one should expect it to return a Frame Parse Error if used in a filmReel implementation.

filmReel concepts: