/
readme.scroll
128 lines (101 loc) · 5.58 KB
/
readme.scroll
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
import header.scroll
permalink index.html
title JTree: Tree Notation SDK for TypeScript & Javascript
startColumns 4
import ciBadges.scroll
# Links
Tree Notation Homepage
https://treenotation.org
Tree Notation Sandbox
https://jtree.treenotation.org/sandbox
Tree Language Designer
https://jtree.treenotation.org/designer
Release Notes
https://jtree.treenotation.org/releaseNotes.html
Tree Notation FAQ
https://faq.treenotation.org
TrueBase
https://truebase.pub/
TypeScript Library
https://github.com/treenotation/jtree
Tree Notation Subreddit
https://reddit.com/r/treenotation
Ohayo - A data science studio powered by Tree Notation
https://github.com/treenotation/ohayo
UnitTests
https://jtree.treenotation.org/sandbox/test.html
PerfTests
https://jtree.treenotation.org/sandbox/perfTests.html
? Who is this package built for?
Jtree is for people who want to design Tree Languages, make Tree editing tools, or use the Tree Component Web Framework.
You can think of jtree as similar to the Java Development Kit, except for Tree Notation instead of Java.
? How do I build a new language?
You can try the Grammar tutorial.
link grammarTutorial.html Grammar tutorial
# Grammar Files
Jtree contains a Tree Language called "Grammar". You can write new Grammar files to define new languages. By creating a grammar file you get a parser, a type checker, syntax highlighting, autocomplete, a compiler, and virtual machine for executing your new language. Jtree also includes a simple web Tree Language Designer.
https://jtree.treenotation.org/designer Designer
To make your language do really interesting things, you'll want to write some code to extend your language nodes in another language that you know. Jtree lets you create new languages using just Tree Notation, Tree Notation + TypeScript, or Tree Notation + Javascript. Tree Notation and Tree Languages can be built with any language, however, not just TypeScript and Javascript. We are looking for volunteers to build libraries/sdks in other host languages.
# Using Jtree
## Quick start
- Open https://gitpod.io/#https://github.com/breck7/jtree
- Run:
code
npm install -g ts-node
npm install .
npm run test
Jtree currently includes over 10 compiled projects (aka "products") and more than a dozen Tree Languages.
# Basic TreeNode library for npm projects:
code
const {TreeNode} = require("jtree/products/TreeNode.js")
const tree = new TreeNode("hello world")
console.log(tree.asString)
# Basic TreeNode library + Grammar Language for the browser:
code
<script src="../../products/Utils.browser.js"></script>
<script src="../../products/TreeNode.browser.js"></script>
<script src="../../products/GrammarLanguage.browser.js"></script>
## jtree "sandbox" web app for exploring base Tree Notation
code
npm install .
npm run local
open http://localhost:3333/
## jtree "Designer" web app for building new Tree Languages
code
npm install .
npm run local
open http://localhost:3333/designer
## TreeComponentFramework for building web apps
This is a web framework still in the research stage. Whether it evolves into a serious line of effort is unknown.
## Sample Languages
More than 12 example Tree Languages for helping with various tasks. See the `langs/` folder.
## Build Tools
If you look at the source, you will also see a set of build tools (such as Builder and TypeScriptRewriter). These are currently undocumented and not recommended for external use.
## Building all tools and running tests
code
npm run build
npm test
# Monorepo
Jtree is a monorepo. With on average over 1 major version released each month for the past 2.5 years, it would take a lot of overhead to constantly be updating 10+ different repositories and modules every month. Once we're more confident in the theory and best practices, it might make sense to break this repo into independent modules.
That being said, we despise unnecessary dependencies as much as anyone. If anyone wants to create some automated submodules built from the projects in this monorepo, to allow for consuming of a smaller subset of the code and dependencies in this module, feel free to do so.
## Visualization of the code base
https://mango-dune-07a8b7110.1.azurestaticapps.net/?repo=breck7%2Fjtree Visualization
image images/diagram.svg
# Development Status
All breaking changes are mentioned in the releaseNotes. We follow semantic versioning, so breaking changes should not happen if you stay on the same major version.
link releaseNotes.html releaseNotes
# Tree Notation Libraries in Other Languages
If you build a Tree Notation library/SDK in another language, let us know and we'll add a link.
If you are working on a Tree Notation library in a new host language, feel free to post an issue or ask for help in the TreeNotation subreddit.
https://reddit.com/r/treenotation subreddit
## How to bump versions
code
npm run updateVersion NEW_NUMBER
# Alternatives Considered
This is the first Tree Notation library in existence, so there were no alternative implementations. Note and Space were predecessors to Tree Notation. If a better alternative low level notation to Tree Notation is possible, it has yet to be discovered.
All that said, the important part of this repo is not the code but the design patterns. Tree Notation is very simple, and you can implement the patterns contained here in your own code without using this library. In fact, that is often the best way to use Tree Notation!
## Editing in Sublime Text
It is helpful to set `"goto_anything_exclude_gitignore": true` to ignore files in gitignore. Read more here.
https://breckyunits.com/code/my-sublime-setttings.html here
# ❤️ Public Domain ❤️
import footer.scroll