30:T826,md`### Passing References While Ji code is just plain text being compiled by the *[Ji Compiler](/@elisk/ji#JiCompiler)* there will be cases where the basic *[Block Begin/End Symbols](/@elisk/ji#BlockBeginSymbol)* are insufficient or simply not needed. While writing Ji code in the Observable platform we can exploit / use the *[Javascript Template Literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)* to pass around variables and functions outside of the Ji code and inject it to be used by symbols and otherwise. For example we might define a symbol and provide it with a function written outside of the Ji code: ~~~js // Block 1 - Function defintion multiply = (left, right) => parseFloat(left) * parseFloat(right) // Block 2 jit\` • ⨕ \${['Multi', multiply]} Three times five equals: 3•5 \` // Block 2 output: Three times five equals: 15 ~~~ This is particulary useful when writing a little bit more than a trivial external code (Javascript or otherwise). Note the notation used in *Block 2*: \`• ⨕ \${['multiply', multiply]}\` - what it's essentially doing is setting the internal variable *\`Multi\`* to the value passed as the second element in the array, the *\`multiply\`* function defined in *Block 1*. #### Define once, use many times When defining an internal variable we only need to define it once, every consecutive usage from the point of definition onword will not require the \`\${['name', var]}\` defintion, and accessing the desired variable only requires to reference it by the name we defined. E.g. ~~~js // Input jit\` ° ⨕ (left, right) => \${['Multi', multiply]}(left, right) * Multi(left, right) The cube of three times five equals: 3°5 \` // Output The cube of three times five equals: 225 ~~~ > Note that each individual use of *Set Symbol* or *Set Word Symbol* does not require to redefine a given variable, so in the case above if we'd try to set another symbol we won't need to define the external variable once again and will be able to access the *Multi* variable defined earlier. `31:T476,md`### Translate While the *Import Symbol* is very useful in some cases it might be a boilerplate-style overhead that can be easily sidestepped by accessing the *jitranslate* property of any *jit* output, allowing you to easily create *Tagged Template* functions to be used just like the *jit* function while preserving the vocabulary generated by the original Ji code. For example we'd like to generate a vocabulary for working with math and quickly use it elsewhere, e.g.: ~~~js // Block 1 - Define maths as a Ji output maths = jit\` ∑ ⨎ (left) => left.split(' ').map(el => parseFloat(el)).filter(isFinite).reduce((acc, el) => acc + el, 0) Max ⨎ (left) => left.split(' ').map(el => parseFloat(el)).filter(isFinite).sort((a, b) => a > b ? 1 : -1).pop() Min ⨎ (left) => left.split(' ').map(el => parseFloat(el)).filter(isFinite).sort((a, b) => a < b ? 1 : -1).pop() \` // Block 2 — Use maths as a tagged template literal jimaths = maths.jitranslate // Block 3 — Use maths as a tagged template literal jimaths\` 14 50 33 1000 ∑ 14 50 33 10 Max 14 50 33 10 Min \` // Block 3 Output Sum: 1097 Maximum: 50 Minimum: 10 ~~~ `32:Tb02,symbolsOverview = ({ [fnToSymbol(terminationSymbol)]: { title: 'Termination Symbol', charname: 'newline', description: `

Newline - terminates the collection of text on the left and executes it.

If there are any pending symbols (i.e. symbol that expect the **right** argument) these symbols will be invoked with the **right** argument being the collected string from the invoked symbol up until the termination symbol

` }, [fnToSymbol(shortTerminationSymbol)]: { title: 'Short Termination Symbol', description: `

Space — The space is called the *Short Terminator* as it will terminate the execution of a symbol before the appearance of a *Termination Symbol* as soon as the *Short Terminator* appears.

It is used primarily by the *Set Word Symbol* and invokes the defined symbol only with the string of text adjacent immediately to the **left** and **right** of the symbol up to and not including the *Short Terminator Symbol* (space).

` }, [fnToSymbol(setSymbol)]: { title: 'Set Symbol', description: `

Set Symbol allow to provide a symbol that may require **left** and **right** arguments and will collect both arguments from previous symbol invocation and up until the next *Termination Symbol*.

Both *Set Symbol* and *Set Word Symbol* will execute the **right** argument provided to it as a Javascript code, and will introduce a *Local Vocabulary* after invocation including the *Block Start Symbol* and *Block End Symbol* to enable writing code spanning multiple lines.

` }, [fnToSymbol(setWordSymbol)]: { title: 'Set Word Symbol', description: `

Set Word Symbol is very similar to *Set Symbol* with the primary difference that symbols defined using *Set Word Symbol* will consume only the immediate strings to the **left** and **right** (if right argument is expected) of the defined symbol, making it possible to use symbols in-line rather than across multiple lines.

` }, [fnToSymbol(importSymbol)]: { title: 'Import Vocabulary Symbol', description: `

` }, [fnToSymbol(vocabularySymbol)]: { title: 'Vocabulary Symbol', description: `

The *Vocabulary Symbol* allows you to quickly peer into the current vocabulary available to the current Ji code. By invoking the *Vocabulary Symbol* you'll print out the current vocabulary enabling you to easily copy a symbol you might need and to debug your Ji code in certain cases.

` } })33:[] 2e:{"title":"Ji Guide","cells":[{"id":0,"value":"md`# Ji Guide`","pinned":false,"hidden":false,"mode":"ojs"},{"id":240,"value":"md`## Using Jit Tagged Template\n\nGet started with Ji simply by creating a [new notebook](/new) or fork this [Ji Starter Template](https://observablehq.com/@elisk/ji-starter) notebook and play with it as is\n\nFeel free to publish your experiments and share with the rest of the community.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":263,"value":"importJit = md`### [Import \\`jit\\`](#importJit)\n\nTo import Jit tagged template function simply add this to your notebook:\n\n~~~js\nimport { jit } from '@elisk/ji'\n~~~\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":37,"value":"import { jit } from '@elisk/ji'","pinned":false,"hidden":false,"mode":"ojs"},{"id":286,"value":"md`## Understanding Ji\n\nIn Ji every character can be defined as a **symbol** that can perform functions based on the **left** and/or **right** values around the symbol.\n\nAny defined symbol in Ji is a function that can receive 0 or more arguments. The behaviour of the symbol function will depend on this function, primarily how many arguments it expects, and what kind of a return value it produces.\n\nFunction implementation is dependant on the environment that Ji is being executed in and the supported languages it provides.\n\nHere in [Observable](/) Ji supports Javascript functions out of the box.\n\nLet's take a look at how we can define symbols in Ji.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":269,"value":"md`## Defining Symbols\n\nJi allows you to define symbols using several ways both as part of your Ji code or as a pre-execution configuration.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":327,"value":"md`By default all symbols that consume a **right** argument will receive the **right** argument input containing everything between the invoked symbol and the nearest [*Termination Symbol*](/@elisk/ji#TerminationSymbol) — newline character.\n\nThere are cases where we'd want to have more than the single line as the input and include other lines as part of it, for those situations you'll need to provide a \\`Function\\` that receives two arguments, \\`state\\` and \\`lines\\`, as the return value of your symbol invocation instead of the actual value. Keep in mind you'll have to handle the termination of the symbol invocation yourself in that case.\n\n> For reference see the [*setSymbol*](/@elisk/ji#setSymbol) and [*setWordSymbol*](/@elisk/ji#setWordSymbol) implementation and their use of a *local vocabulary* to provide the *Block Start* and *Block End* symbols.\n\nE.g.:\n\n~~~js\n(left, right) => (state, lines) => '...'\n~~~\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":272,"value":"md`### Set Symbol — \"${fnToSymbol(setSymbol)}\"\n\nUsing the [Set Symbol](/@elisk/ji#SetSymbol) (default symbol: ${fnToSymbol(setSymbol)}) we can define a symbol by providing the symbol we'd like to define on the **left** side and the javascript code we want to handle the input on the **right** side.\n\nExample:\n\n~~~md\n🕰 ⨎ () => \\`The time is: \\${Date}\\`\n\n🕰\n~~~\n\nOutput: \n\n~~~md\nThe time is: Sat Aug 24 2019 20:27:30 GMT+0300 (Israel Daylight Time)\n~~~\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":310,"value":"md`### Set Word Symbol — \"${fnToSymbol(setWordSymbol)}\"\n\nUsing the [Set Word Symbol](/@elisk/ji#SetWordSymbol) (default symbol: ${fnToSymbol(setWordSymbol)}) we can define a symbol by providing the symbol we'd like to define on the **left** side and the javascript code we want to handle the input on the **right** side.\n\nThe difference between a *Regular Symbol* defined using ${fnToSymbol(setSymbol)} (\\`setSymbol\\`) and a *Word Symbol* defined using ${fnToSymbol(setWordSymbol)} (\\`setWordSymbol\\`) is that the latter will take only the immediate **left** and **right** inputs up to the nearest [*Short Termination Symbol*](/@elisk/ji#ShortTerminationSymbol) (space) or [*Termination Symbol*](/@elisk/ji#TerminationSymbol) (newline).\n\nExample:\n\n~~~md\n\n⁒ ⨕ (left, right) => {\n const nl = parseFloat(left)\n const nr = parseFloat(right)\n return nl + (nl * (nr / 100))\n}\n\n200 take 30%: 200⁒30\n~~~\n\nOutput: \n\n~~~md\n200 take 30%: 260\n~~~\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":537,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":349,"value":"d = md`## Default Symbols\n\nJi comes with a small set of predefined symbols that you can use as part of any new Ji code. These symbols are the basic building blocks of your Ji code.\n\nAlthough they're provided by default they can be overriden, modified, and removed altogether to fit whatever writing style is desired.\n\nLet's take a look at the list of these default symbol along with a short description of their function:\n\n### Termination Symbols\n${await listSymbols(terminationSymbol, shortTerminationSymbol)}\n\n### Set Symbols\n${await listSymbols(setSymbol, setWordSymbol)}\n\n### Import Symbol\n${await listSymbols(importSymbol)}\n\n### Vocabulary Symbol\n${await listSymbols(vocabularySymbol)}\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":586,"value":"md`## Importing and Exporting\n\nDefining symbols inside your Ji code is swell, but sometimes we'll want to import an already existing set of symbols from a previously defined list of symbols generated by another Ji code.\n\nFor that we have a few tools provided by the default Ji implemetation, starting with the *Import Symbol* and the *Transport* and *Translate* functionalities described below.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":607,"value":"md`### Import\n\nThe *Import Symbol* (default: ${fnToSymbol(importSymbol)}) allows you to quickly import an existing vocabulary generated by executing Ji code. We can use the *Import Symbol* to consume an output of Ji code.\n\nTo use the *Import Symbol* define a Ji output outside of your Ji code and pass in the output to the *Import Symbol* **right** argument; e.g.\n\n~~~js\n// Block 1 — Vocabulary definition\nmyVocabulary = jit\\`\nœ ⨎ (left, right) => \\`\\${right} said: \"\\${left}\"\\`\n\\`\n\n// Block 2 — Vocabulary use in Ji\njit\\`\n⨭ \\${['myVocas', myVocabulary]}\nThis is the best of all possible worlds œ Gottfried Wilhelm Leibniz\n\\`\n\n// Block 2 — Output\nGottfried Wilhelm Leibniz said: \"This is the best of all possible worlds \"\n\n\n~~~\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":597,"value":"md`### Transport\n\nWhen generating an output using the *jit* function the returning object will containing a few additional properties: \\`transport\\`, \\`jitranslate\\`, and \\`plain\\`.\n\nThe \\`transport\\` property is the final state of the Ji code after the code has fininshed executing, and contains (but not limited to) the following properties:\n\n~~~md\nvocabulary - Object containing the defined symbols available for execution\ninput - The original input string provided\ncontext - Any contextual variables passed to this execution\ncollected - Collected string that wasn't processed by a symbol yet\noutput - Output string after code processing\n~~~\n\nThis property of the resulting output of Ji execution can be used to extract the compiled code and use it elsewhere. And indeed it's used by the *Import Symbol* described earlier and the *Ji Translate* functionality described next.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":606,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":343,"value":"md`# Advanced Topics`","pinned":false,"hidden":false,"mode":"ojs"},{"id":255,"value":"withDebug = md`### [Import with Debugging](#withDebug)\n\nTo enable verbose mode while working with Ji which can assist in debugging and tracing errors, you can import \\`jit\\` with \\`verbos\\` set to true, like in the following example:\n\n#### 1. Create a truthy cell\n\n~~~js\ndoDebug = true\n~~~\n\n#### 2. Import using \\`with\\` statement\n~~~js\nimport { jit }\nwith { doDebug as verbos }\nfrom '@elisk/ji'\n~~~\n\nYour console will be filled now with advanced debugging details for all your programming needs.\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":711,"value":"md`# Appendix`","pinned":false,"hidden":false,"mode":"ojs"},{"id":371,"value":"import { runes } from '@elisk/ji'","pinned":false,"hidden":false,"mode":"ojs"},{"id":274,"value":"import { setSymbol, setWordSymbol, terminationSymbol, shortTerminationSymbol, importSymbol, vocabularySymbol, fnToSymbol } from '@elisk/ji'","pinned":false,"hidden":false,"mode":"ojs"},{"id":16,"value":"_ = require('lodash')","pinned":false,"hidden":false,"mode":"ojs"},{"id":431,"value":"symbolURL = 'https://graphemica.com/'","pinned":false,"hidden":false,"mode":"ojs"},{"id":358,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":374,"value":"symbolDef = async (symbol, { title, charname, description } = {}) =>\n `

\n `${symbol.replace('\\n', '\\\\n').replace(' ', \"' '\")}` — `${title || 'Missing Symbol Definition'}`\n

\n dec: ${symbol.codePointAt(0)}\n — hex: ${_.padStart(symbol.codePointAt(0).toString(16).toUpperCase(), 4, '0')}\n — name: ${charname || await Charname(symbol)}

${description || 'Missing Symbol Description'}

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":445,"value":"Charname = async symbol => {\n const proxy = 'https://observable-cors.glitch.me/'\n const baseURL = 'https://ucdapi.org/unicode/latest/codepoint/dec/'\n const d3 = await require('d3')\n const url = `${proxy}${baseURL}${symbol.codePointAt(0)}`\n const result = await d3.json(url)\n \n return (!!result && result.name && result.name.toLowerCase()) || ''\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":370,"value":"listSymbols = async (...symbols) =>\n `

\n${(\n await Promise.all(symbols\n .map(symbol => fnToSymbol(symbol))\n .map((symbol) => symbolDef(symbol, symbolsOverview[symbol]))\n )\n).join(`

`)}\n

`","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W33","stdlib":"1","titling":"auto"}

\n ${symbol.replace('\\n', '\\\\n').replace(' ', \"' '\")} — ${title || 'Missing Symbol Definition'}\n

\n `${symbol.replace('\\n', '\\\\n').replace(' ', \"' '\")}` — `${title || 'Missing Symbol Definition'}`\n