diff --git a/docs/.eleventy.js b/docs/.eleventy.js index 5bbd2fc..ad4d610 100644 --- a/docs/.eleventy.js +++ b/docs/.eleventy.js @@ -3,8 +3,8 @@ const EleventyGoogleFonts = require("eleventy-google-fonts"); const EleventyFeatherIcons = require('eleventy-plugin-feathericons'); const HighlightJS = require('highlight.js') -const { useDocument } = require('@terrace/js/document') -const { createFileReader } = require('@terrace/js/readers/node-readline') +const { useDocument } = require('@terrace-lang/js/document') +const { createFileReader } = require('@terrace-lang/js/readers/node-readline') const parsePage = require('./src/parser/page.js'); module.exports = function (config) { diff --git a/docs/package.json b/docs/package.json index e29743a..e8ebd40 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,5 +1,5 @@ { - "name": "@terrace/docs", + "name": "@terrace-lang/docs", "private": true, "license": "MIT", "scripts": { @@ -11,7 +11,7 @@ "@11ty/eleventy-plugin-vite": "^4.0.0", "@sindresorhus/slugify": "^2.2.0", "@tailwindcss/typography": "^0.5.9", - "@terrace/js": "workspace:*", + "@terrace-lang/js": "workspace:*", "eleventy-google-fonts": "^0.1.0", "eleventy-plugin-feathericons": "^1.0.1", "highlight.js": "^11.7.0", diff --git a/docs/src/_includes/nodes/CodeBlock.njk b/docs/src/_includes/nodes/CodeBlock.njk index 65b3636..50c90e4 100644 --- a/docs/src/_includes/nodes/CodeBlock.njk +++ b/docs/src/_includes/nodes/CodeBlock.njk @@ -1,5 +1,9 @@ {% macro render(node) %} 
{{ node.text | highlight(node.language) | safe }}
{% endmacro %} diff --git a/docs/src/_includes/nodes/CodeExample.njk b/docs/src/_includes/nodes/CodeExample.njk index 01352f6..28736aa 100644 --- a/docs/src/_includes/nodes/CodeExample.njk +++ b/docs/src/_includes/nodes/CodeExample.njk @@ -13,7 +13,7 @@ set languageMeta = { {% macro render(node) %}
- {% macro Language(id, code, isFirst) %} + {% macro Language(node, example, isFirst) %}
- - {{ languageMeta[id].name }} + + {{ example.name or languageMeta[example.language].name }} 
{{ code | highlight(id) | safe }}
+ >{{ example.code | highlight(example.language) | safe }}
{% endmacro %} {% set isFirst = true %} - {% for id, code in node.languages %} - {{ Language(id, code, true if isFirst else false) }} + {% for example in node.examples %} + {{ Language(node, example, true if isFirst else false) }} {% set isFirst = false %} {% endfor %}
diff --git a/docs/src/_includes/nodes/Heading.njk b/docs/src/_includes/nodes/Heading.njk index a783d8c..67bc543 100644 --- a/docs/src/_includes/nodes/Heading.njk +++ b/docs/src/_includes/nodes/Heading.njk @@ -4,13 +4,26 @@ '3': 'text-lg md:text-2xl font-light' } %} +{% set levelLinkClasses = { + '1': 'border-transparent hover:border-primary-600', + '2': 'border-transparent hover:border-primary-600', + '3': 'border-transparent hover:border-current' +} %} + {% macro render(node) %} - {{ node.text | safe }} + {% if node.href %} + {{ node.text | safe }} + {% else %} + {{ node.text | safe }} + {% endif %} {% endmacro %} diff --git a/docs/src/_includes/nodes/Navbar.njk b/docs/src/_includes/nodes/Navbar.njk index d8b94d2..89f0393 100644 --- a/docs/src/_includes/nodes/Navbar.njk +++ b/docs/src/_includes/nodes/Navbar.njk @@ -27,11 +27,10 @@ lg:pointer-events-auto lg:relative lg:top-0 lg:px-0 lg:flex-row lg:flex-1 lg:h-20 lg:bg-neutral-800 lg:text-white "> - {{ navlink("/docs/c/", "Docs", ctx.url) }} + {{ navlink("/docs/javascript/", "Docs", ctx.url) }} {{ navlink("/examples/", "Examples", ctx.url) }} {{ navlink("/about/", "About", ctx.url) }} {{ navlink("/contribute/", "Contribute", ctx.url) }} - Contribute
{{ Node('SearchBox', { class: 'w-full lg:w-72' }) }}
{{ Node('Icon', { icon: 'github' }) }}
Code
diff --git a/docs/src/docs/c/index.tce b/docs/src/docs/c.tce similarity index 88% rename from docs/src/docs/c/index.tce rename to docs/src/docs/c.tce index 1777e8a..eed8c9a 100644 --- a/docs/src/docs/c/index.tce +++ b/docs/src/docs/c.tce @@ -1,5 +1,5 @@ layout layout.njk -title Documentation - Terrace +title C Documentation - Terrace description C language documentation for the Terrace programming language @@ -19,7 +19,7 @@ Section light Markdown Documentation is available for the following languages: - [C](/docs/c/) - 10% Complete - - [JavaScript](/docs/javascript/) - 0% Complete + - [JavaScript](/docs/javascript/) - 20% Complete - [Python](/docs/python/) - 0% Complete Heading 2 Getting Started @@ -111,11 +111,20 @@ Section light Heading 2 Core API class mt-12 - Heading 3 Type: terrace_linedata_t + Heading 3 terrace_linedata_t class my-6 + CodeBlock c + typedef struct terrace_linedata_s { + char indent; + unsigned int level; + unsigned int offsetHead; + unsigned int offsetTail; + } terrace_linedata_t; - Heading 3 Function: terrace_parse_line + Heading 3 terrace_parse_line() class my-6 + CodeBlock c + void terrace_parse_line(char* line, terrace_linedata_t *lineData) Heading 2 Contributing class mt-12 diff --git a/docs/src/docs/javascript.tce b/docs/src/docs/javascript.tce new file mode 100644 index 0000000..66fddc3 --- /dev/null +++ b/docs/src/docs/javascript.tce @@ -0,0 +1,262 @@ +layout layout.njk +title JavaScript Documentation - Terrace +description + JavaScript language documentation for the Terrace programming language + +Section light + class flex flex-col md:flex-row gap-16 + + Block + class w-full lg:w-1/3 + TableOfContents + + Block + class max-w-prose + + Heading 1 Terrace JavaScript Documentation + class -ml-2 + + Markdown + Documentation is available for the following languages: + - [C](/docs/c/) - 10% Complete + - [JavaScript](/docs/javascript/) - 20% Complete + - [Python](/docs/python/) - 0% Complete + + Heading 2 Getting Started + class mt-12 mb-6 + Markdown + Install Terrace using [NPM](https://www.npmjs.com/): + + CodeBlock bash + # NPM (https://npmjs.com) + $ npm install @terrace-lang/js + + # PNPM (https://pnpm.io/) + $ pnpm install @terrace-lang/js + + # Yarn (https://yarnpkg.com/) + $ yarn add @terrace-lang/js + + Heading 2 Recipes + class mt-12 + + Heading 3 Read object properties + class mb-2 + Markdown + Read known properties from a Terrace block and write them to an object. + CodeBlock javascript + // Provides simple convenience functions over the core parser + // CommonJS: const { useDocument } = require('@terrace-lang/js/document') + import { useDocument } from '@terrace-lang/js/document' + // A helper for iterating over a string line-by-line + // CommonJS: const { createStringReader } = require('@terrace-lang/js/readers/js-string') + import { createStringReader } from '@terrace-lang/js/readers/js-string' + + const input = ` + object + string_property An example string + numeric_property An example property + ` + + const output = { + string_property: null, + numeric_property: null + } + + // useDocument returns convenience functions + const { next, level, head, tail, match } = useDocument(createStringReader(input)) + + // next() parses the next line in the document + while (await next()) { + // match('object') is equivalent to head() === 'object' + // Essentially: "If the current line starts with 'object'" + if (match('object')) { + const objectLevel = level() + // When we call next with a parent level it, + // only iterates over lines inside the parent block + while (await next(objectLevel)) { + // tail() returns the part of the current line after the first space + if (match('string_property')) output.string_property = tail() + // parseFloat() here the string tail() to a numeric float value + if (match('numeric_property')) output.numeric_property = parseFloat(tail()) + } + } + } + + console.dir(output) + + Markdown + Read *all* properties as strings from a Terrace block and write them to an object. + CodeBlock javascript + // Provides simple convenience functions over the core parser + // CommonJS: const { useDocument } = require('@terrace-lang/js/document') + import { useDocument } from '@terrace-lang/js/document' + // A helper for iterating over a string line-by-line + // CommonJS: const { createStringReader } = require('@terrace-lang/js/readers/js-string') + import { createStringReader } from '@terrace-lang/js/readers/js-string' + + const input = ` + object + property1 Value 1 + property2 Value 2 + random_property igazi3ii4quaC5OdoB5quohnah1beeNg + ` + + const output = {} + + // useDocument returns convenience functions + const { next, level, head, tail, match } = useDocument(createStringReader(input)) + + // next() parses the next line in the document + while (await next()) { + // match('object') is equivalent to head() === 'object' + // Essentially: "If the current line starts with 'object'" + if (match('object')) { + const objectLevel = level() + // When we call next with a parent level it, + // only iterates over lines inside the parent block + while (await next(objectLevel)) { + // Skip empty lines + if (!line()) continue + // Add any properties to the object as strings using the + // line head() as the key and tail() as the value + output[head()] = tail() + } + } + } + + console.dir(output) + + Heading 2 Core API + class mt-12 + + Heading 3 LineData + class my-6 + CodeBlock typescript + type LineData = { + line: string; + indent: string; + level: number; + offsetHead: number; + offsetTail: number; + } + + Heading 3 createLineData() + class my-6 + CodeBlock typescript + function createLineData(line: string = '', indent: string = ' '): LineData + CodeBlock javascript + import { createLineData } from '@terrace-lang/js/parser' + + Heading 3 parseLine() + class my-6 + CodeBlock typescript + function parseLine(lineData: LineData): LineData + CodeBlock javascript + import { parseLine } from '@terrace-lang/js/parser' + + Heading 2 Document API + class mt-12 + + Heading 3 useDocument() + class my-6 + CodeBlock typescript + function useDocument (reader: Reader, indent: string = ' '): Document + CodeBlock javascript + import { useDocument } from '@terrace-lang/js/document' + + Heading 3 Document + class my-6 + CodeBlock typescript + type Document = { + next: (startLevel?: number) => Promise + level: () => number, + line: (startOffset?: number) => string, + head: () => string, + tail: () => string, + match: (matchHead: string) => boolean + } + + Heading 3 Document.next() + class my-6 + CodeBlock typescript + next: (startLevel?: number) => Promise + CodeBlock javascript + import { useDocument } from '@terrace-lang/js/document' + const { next } = useDocument(...) + + Heading 3 Document.level() + class my-6 + CodeBlock typescript + level: () => number + CodeBlock javascript + import { useDocument } from '@terrace-lang/js/document' + const { level } = useDocument(...) + + Heading 3 Document.line() + class my-6 + CodeBlock typescript + line: (startOffset?: number) => string + CodeBlock javascript + import { useDocument } from '@terrace-lang/js/document' + const { line } = useDocument(...) + + Heading 3 Document.head() + class my-6 + CodeBlock typescript + head: () => string + CodeBlock javascript + import { useDocument } from '@terrace-lang/js/document' + const { head } = useDocument(...) + + Heading 3 Document.tail() + class my-6 + CodeBlock typescript + tail: () => string + CodeBlock javascript + import { useDocument } from '@terrace-lang/js/document' + const { tail } = useDocument(...) + + Heading 3 Document.match() + class my-6 + CodeBlock typescript + match: (matchValue: string) => boolean + CodeBlock javascript + import { useDocument } from '@terrace-lang/js/document' + const { match } = useDocument(...) + + Heading 2 Reader API + class mt-12 + + Heading 3 Reader + class my-6 + CodeBlock typescript + type Reader = () => string|null|Promise + + Heading 3 createStringReader() + class my-6 + CodeBlock typescript + function createFileReader(path: string): Reader + CodeBlock javascript + import { createStdinReader } from '@terrace-lang/js/readers/js-string' + + Heading 3 createFileReader() + class my-6 + CodeBlock typescript + function createFileReader(path: string): Reader + CodeBlock javascript + import { createStdinReader } from '@terrace-lang/js/readers/node-readline' + + Heading 3 createStdinReader() + class my-6 + CodeBlock typescript + function createStdinReader(): Reader + CodeBlock javascript + import { createStdinReader } from '@terrace-lang/js/readers/node-readline' + + Heading 2 Contributing + class mt-12 + +Section dark + Footer + class w-full diff --git a/docs/src/index.tce b/docs/src/index.tce index 5a10764..94ffcc0 100644 --- a/docs/src/index.tce +++ b/docs/src/index.tce @@ -21,11 +21,11 @@ Section light Terrace gets out of your way to let you - **just write** Button primary - href /docs/getting-started + href /docs/javascript/#getting-started Get Started CodeExample - class min-h-[350px] + height 350px terrace title Terrace - A simple structured data language description @@ -175,6 +175,7 @@ Section dark class flex gap-4 items-center mb-4 Icon info Heading 3 About + href /about/ class mb-0 Markdown Why does Terrace exist? What is it based on? What are the development goals? @@ -185,6 +186,7 @@ Section dark class flex gap-4 items-center mb-4 Icon file-text Heading 3 Documentation + href /docs/javascript/ class mb-0 Markdown Setup instructions, API documentation, and recipes for how to perform common tasks with Terrace. diff --git a/docs/src/parser/nodes/CodeExample.js b/docs/src/parser/nodes/CodeExample.js index d4506fe..bf7dd1e 100644 --- a/docs/src/parser/nodes/CodeExample.js +++ b/docs/src/parser/nodes/CodeExample.js @@ -8,15 +8,23 @@ module.exports = async (doc, rootLevel) => { const node = { type: head(), class: '', - languages: {} + summaryClass: 'mb-[400px]', + preClass: 'max-h-[400px]', + examples: [] } while (await next(rootLevel)) { if (match('class')) node.class = tail() + if (match('summary-class')) node.summaryClass = tail() + if (match('pre-class')) node.preClass = tail() - const languageLevel = level() + const exampleLevel = level() if (languages.includes(head())) { - node.languages[head()] = await contentAsText(doc, languageLevel) + node.examples.push({ + language: head(), + name: tail() || '', + code: await contentAsText(doc, exampleLevel) + }) } } diff --git a/docs/src/parser/nodes/Heading.js b/docs/src/parser/nodes/Heading.js index 6fb5310..124a173 100644 --- a/docs/src/parser/nodes/Heading.js +++ b/docs/src/parser/nodes/Heading.js @@ -14,11 +14,13 @@ module.exports = async function (doc, rootLevel, pageData) { text, slug, class: '', + href: '', children: [] } while (await next(rootLevel)) { if (match('class')) node.class = tail() + if (match('href')) node.href = tail() } pageData.headings.push(node) diff --git a/docs/src/parser/nodes/Logo.js b/docs/src/parser/nodes/Logo.js index c7e0941..63afc44 100644 --- a/docs/src/parser/nodes/Logo.js +++ b/docs/src/parser/nodes/Logo.js @@ -6,17 +6,11 @@ module.exports = async function (doc, rootLevel) { const node = { type: head(), variant: tail() || 'neutral', - class: '', - href: '', - text: '' + class: '' } while (await next(rootLevel)) { if (match('class')) node.class = tail() - else if (match('href')) node.href = tail() - else { - node.text = await contentAsText(doc, rootLevel, true) - } } return node diff --git a/docs/tailwind.config.js b/docs/tailwind.config.js index 61b059e..cb7dba0 100644 --- a/docs/tailwind.config.js +++ b/docs/tailwind.config.js @@ -38,7 +38,8 @@ module.exports = { info: colors.sky, }, fontSize: { - sm: '0.8rem', + xs: '0.8rem', + sm: '1rem', base: '1.125rem', xl: '1.25rem', '2xl': '1.563rem', diff --git a/package.json b/package.json index 5d72239..91d1e24 100644 --- a/package.json +++ b/package.json @@ -1,16 +1,16 @@ { - "name": "@terrace/repo", + "name": "@terrace-lang/repo", "private": true, "type": "module", "scripts": { "build:repo": "node ./repo/build.js", "build": "turbo run build --cache-dir=.turbo", "dev": "turbo run dev --no-cache --force", - "test": "turbo run test --filter=@terrace/test --no-cache --force" + "test": "turbo run test --filter=@terrace-lang/test --no-cache --force" }, "devDependencies": { - "@terrace/js": "workspace:*", + "@terrace-lang/js": "workspace:*", "turbo": "^1.7.3", "jest": "^29.4.1" } -} \ No newline at end of file +} diff --git a/packages/c/package.json b/packages/c/package.json index 1feac9b..223043f 100644 --- a/packages/c/package.json +++ b/packages/c/package.json @@ -1,5 +1,5 @@ { - "name": "@terrace/c", + "name": "@terrace-lang/c", "version": "0.0.1", "license": "MIT", "scripts": { diff --git a/packages/js/package.json b/packages/js/package.json index 541fa2a..883483e 100644 --- a/packages/js/package.json +++ b/packages/js/package.json @@ -1,5 +1,5 @@ { - "name": "@terrace/js", + "name": "@terrace-lang/js", "version": "0.0.1", "license": "MIT", "type": "module", diff --git a/packages/js/src/document.ts b/packages/js/src/document.ts index 6fd60b5..f853063 100644 --- a/packages/js/src/document.ts +++ b/packages/js/src/document.ts @@ -7,7 +7,7 @@ export type Document = { line: (startOffset?: number) => string, head: () => string, tail: () => string, - match: (matchHead: string) => boolean + match: (matchValue: string) => boolean } export function useDocument (reader: Reader, indent: string = ' '): Document { @@ -43,7 +43,7 @@ export function useDocument (reader: Reader, indent: string = ' '): Document { const line = (startOffset: number = lineData.offsetHead) => lineData.line.slice(startOffset) const head = () => lineData.line.slice(lineData.offsetHead, lineData.offsetTail) const tail = () => lineData.line.slice(lineData.offsetTail + 1) // Skip the space - const match = (matchHead: string): boolean => matchHead === head() + const match = (matchValue: string): boolean => matchValue === head() return { next, diff --git a/packages/js/test/index.js b/packages/js/test/index.js index 251ba99..237f6c1 100644 --- a/packages/js/test/index.js +++ b/packages/js/test/index.js @@ -1,5 +1,5 @@ -import { createLineData, parseLine, useDocument } from '@terrace/js' -import { createStdinReader } from '@terrace/js/readers/node-readline' +import { createLineData, parseLine, useDocument } from '@terrace-lang/js' +import { createStdinReader } from '@terrace-lang/js/readers/node-readline' const testName = process.argv[2] diff --git a/packages/python/package.json b/packages/python/package.json index 6aa0267..86b3307 100644 --- a/packages/python/package.json +++ b/packages/python/package.json @@ -1,5 +1,5 @@ { - "name": "@terrace/python", + "name": "@terrace-lang/python", "version": "0.0.1", "license": "MIT", "scripts": { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 021b399..85da28e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -4,11 +4,11 @@ importers: .: specifiers: - '@terrace/js': workspace:* + '@terrace-lang/js': workspace:* jest: ^29.4.1 turbo: ^1.7.3 devDependencies: - '@terrace/js': link:packages/js + '@terrace-lang/js': link:packages/js jest: 29.4.1 turbo: 1.7.3 @@ -18,7 +18,7 @@ importers: '@11ty/eleventy-plugin-vite': ^4.0.0 '@sindresorhus/slugify': ^2.2.0 '@tailwindcss/typography': ^0.5.9 - '@terrace/js': workspace:* + '@terrace-lang/js': workspace:* eleventy-google-fonts: ^0.1.0 eleventy-plugin-feathericons: ^1.0.1 highlight.js: ^11.7.0 @@ -30,7 +30,7 @@ importers: '@11ty/eleventy-plugin-vite': 4.0.0 '@sindresorhus/slugify': 2.2.0 '@tailwindcss/typography': 0.5.9_tailwindcss@3.2.6 - '@terrace/js': link:../packages/js + '@terrace-lang/js': link:../packages/js eleventy-google-fonts: 0.1.0 eleventy-plugin-feathericons: 1.0.1 highlight.js: 11.7.0 @@ -40,13 +40,13 @@ importers: experiments/lesson-plans: specifiers: - '@terrace/js': workspace:* + '@terrace-lang/js': workspace:* ejs: ^3.1.8 humanize-duration: ^3.27.3 nunjucks: ^3.2.3 parse-duration: ^1.0.2 dependencies: - '@terrace/js': link:../../packages/js + '@terrace-lang/js': link:../../packages/js ejs: 3.1.8 humanize-duration: 3.28.0 nunjucks: 3.2.3 @@ -68,13 +68,13 @@ importers: test: specifiers: - '@terrace/c': workspace:* - '@terrace/js': workspace:* - '@terrace/python': workspace:* + '@terrace-lang/c': workspace:* + '@terrace-lang/js': workspace:* + '@terrace-lang/python': workspace:* dependencies: - '@terrace/c': link:../packages/c - '@terrace/js': link:../packages/js - '@terrace/python': link:../packages/python + '@terrace-lang/c': link:../packages/c + '@terrace-lang/js': link:../packages/js + '@terrace-lang/python': link:../packages/python packages: diff --git a/repo/build.js b/repo/build.js index 4f44f5e..e8fb498 100644 --- a/repo/build.js +++ b/repo/build.js @@ -1,6 +1,6 @@ import fs from 'node:fs/promises' -import { useDocument } from '@terrace/js' -import { createFileReader } from '@terrace/js/readers/node-readline' +import { useDocument } from '@terrace-lang/js' +import { createFileReader } from '@terrace-lang/js/readers/node-readline' function useHelpers({ next, level, head, tail }) { diff --git a/repo/package.tce b/repo/package.tce index 2e319b7..1a9755e 100644 --- a/repo/package.tce +++ b/repo/package.tce @@ -1,6 +1,6 @@ #schema package -name @terrace/repo +name @terrace-lang/repo private true type module @@ -8,9 +8,9 @@ scripts build:repo node ./repo/build.js build turbo run build --cache-dir=.turbo dev turbo run dev --no-cache --force - test turbo run test --filter=@terrace/test --no-cache --force + test turbo run test --filter=@terrace-lang/test --no-cache --force devDependencies - @terrace/js workspace:* + @terrace-lang/js workspace:* turbo ^1.7.3 jest ^29.4.1 diff --git a/test/helpers.js b/test/helpers.js index 56317cf..ec722bd 100644 --- a/test/helpers.js +++ b/test/helpers.js @@ -1,8 +1,8 @@ import { expect } from 'chai' import fs from 'node:fs/promises' import { execSync } from 'node:child_process' -import { useDocument } from '@terrace/js' -import { createFileReader } from '@terrace/js/readers/node-readline' +import { useDocument } from '@terrace-lang/js' +import { createFileReader } from '@terrace-lang/js/readers/node-readline' export async function loadTestMap(path) { const { next, level, head, tail, line, match } = useDocument(createFileReader(path)) diff --git a/test/package.json b/test/package.json index 12e3a7c..2ca5c82 100644 --- a/test/package.json +++ b/test/package.json @@ -1,12 +1,12 @@ { - "name": "@terrace/test", + "name": "@terrace-lang/test", "type": "module", "scripts": { "test": "NODE_OPTIONS=--experimental-vm-modules NODE_NO_WARNINGS=1 jest" }, "dependencies": { - "@terrace/js": "workspace:*", - "@terrace/c": "workspace:*", - "@terrace/python": "workspace:*" + "@terrace-lang/js": "workspace:*", + "@terrace-lang/c": "workspace:*", + "@terrace-lang/python": "workspace:*" } }