https://github.com/blackglory/romast
🌿 Renderable Org-Mode Abstract Syntax Tree.
https://github.com/blackglory/romast
browser esm library nodejs npm-package typescript
Last synced: 5 months ago
JSON representation
🌿 Renderable Org-Mode Abstract Syntax Tree.
- Host: GitHub
- URL: https://github.com/blackglory/romast
- Owner: BlackGlory
- License: mit
- Created: 2021-08-21T06:33:27.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-02-27T13:15:24.000Z (over 2 years ago)
- Last Synced: 2024-12-28T17:00:59.932Z (over 1 year ago)
- Topics: browser, esm, library, nodejs, npm-package, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/romast
- Size: 1.47 MB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# romast
**R**enderable **O**rg-**M**ode **A**bstract **S**yntax **T**ree.
romast is an easy-to-render version of [oast v3],
the new AST is designed to render nodes directly from AST to any platform, e.g. React.
[oast v3]: https://github.com/orgapp/orgajs
## Install
```sh
npm install --save romast
# or
yarn add romast
```
## Usage
```ts
import { parse } from 'romast'
import { dedent } from 'extra-tags'
const org = dedent`
* Romast
Lorem ipsum dolor sit amet,
consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Duis aute irure dolor in reprehenderit in voluptate
velit esse cillum dolore eu fugiat nulla pariatur.
`
const romast = parse(org)
// {
// "type": "document",
// "children": [
// {
// "type": "section",
// "level": 1,
// "headline": {
// "type": "headline",
// "tags": [],
// "children": [
// {
// "type": "text",
// "value": "Romast"
// }
// ]
// },
// "children": [
// {
// "type": "paragraph",
// "children": [
// {
// "type": "text",
// "value": "Lorem ipsum dolor sit amet,"
// },
// {
// "type": "newline"
// },
// {
// "type": "text",
// "value": "consectetur adipiscing elit,"
// },
// {
// "type": "newline"
// },
// {
// "type": "text",
// "value": "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
// }
// ]
// },
// {
// "type": "paragraph",
// "children": [
// {
// "type": "text",
// "value": "Duis aute irure dolor in reprehenderit in voluptate"
// },
// {
// "type": "newline"
// },
// {
// "type": "text",
// "value": "velit esse cillum dolore eu fugiat nulla pariatur."
// }
// ]
// }
// ]
// }
// ]
// }
```
## API
### AST
```ts
interface Node {
type: string
}
interface Parent {
children: Node[]
}
interface ParentOf extends Parent {
children: T
}
type BlockNode =
| Document
| Section
| Headline
| Paragraph
| Example
| Source
| Quote
| List
| ListItem
| Table
| TableRowGroup
| TableRow
| TableCell
| HorizontalRule
| Drawer
type InlineNode =
| Footnote
| InlineFootnote
| Link
| Text
| Bold
| Verbatim
| Italic
| Strikethrough
| Underlined
| Code
| Newline
type DocumentContent =
| UniversalBlockContent
| Section
| Newline
type SectionContent =
| UniversalBlockContent
| Section
type ListContent = List | ListItem
type UniversalBlockContent =
| Paragraph
| Example
| Source
| Quote
| Drawer
| List
| Table
| HorizontalRule
type UniversalInlineContent =
| Link
| Text
| Bold
| Verbatim
| Italic
| Strikethrough
| Underlined
| Code
| Footnote
| InlineFootnote
| Newline
interface Document extends ParentOf {
type: 'document'
}
interface Section extends ParentOf {
type: 'section'
level: number
headline: Headline
}
interface Headline extends Node, ParentOf {
type: 'headline'
tags: string[]
}
interface Paragraph extends Node, ParentOf {
type: 'paragraph'
}
interface Example extends Node {
type: 'example'
params: string[]
value: string
}
interface Source extends Node {
type: 'source'
params: string[]
value: string
}
interface Quote extends Node {
type: 'quote'
value: string
}
interface List extends Node, ParentOf {
type: 'list'
indent: number
ordered: boolean
}
interface ListItem extends Node, ParentOf {
type: 'listItem'
indent: number
checked: boolean | null
term: string | null
}
interface Table extends Node, ParentOf {
type: 'table'
header: TableRowGroup | null
}
interface TableRowGroup extends Node, ParentOf {
type: 'tableRowGroup'
}
interface TableRow extends Node, ParentOf {
type: 'tableRow'
}
interface TableCell extends Node, ParentOf {
type: 'tableCell'
}
interface HorizontalRule extends Node {
type: 'horizontalRule'
}
interface Footnote extends Node, ParentOf {
type: 'footnote'
}
interface InlineFootnote extends Node, ParentOf {
type: 'inlineFootnote'
}
interface Newline extends Node {
type: 'newline'
}
interface Drawer extends Node, ParentOf {
type: 'drawer'
name: string
}
interface Link extends Node, ParentOf {
type: 'link'
protocol: 'internal' | string
url: string
}
interface Text extends Node {
type: 'text'
value: string
}
interface Bold extends Node {
type: 'bold'
value: string
}
interface Verbatim extends Node {
type: 'verbatim'
value: string
}
interface Italic extends Node {
type: 'italic'
value: string
}
interface Strikethrough extends Node {
type: 'strikethrough'
value: string
}
interface Underlined extends Node {
type: 'underlined'
value: string
}
interface Code extends Node {
type: 'code'
value: string
}
```
### parse
```ts
function parse(text: string, strict: boolean = false): AST.Document
```
Limited by the parser, The analysis results may have non-compliant nodes.
If `strict` is `true`, an `UnknownNodeError` will be thrown when there are non-compliant nodes.
If `strict` is `false`, theses non-compliant are simply ignored.
### utils
#### builder
```ts
import * as Builder from 'romast/utils/builder'
```
Each romast node has a corresponding builder.
#### is
```ts
import * as Is from 'romast/utils/is'
```
Each romast node has a corresponding `is` function.
#### flatMap
```ts
import { flatMap } from 'romast/utils/flat-map'
function flatMap(
node: AST.Node
, fn: (node: AST.Node) => AST.Node[]
): AST.Node[]
```
#### map
```ts
import { map } from 'romast/utils/map'
function map(
node: AST.Node
, fn: (node: AST.Node) => AST.Node
): AST.Node
```
#### filter
```ts
import { filter } from 'romast/utils/filter'
function filter(
node: AST.Node
, predicate: (node: AST.Node) => unknown
): AST.Node | undefined
```
#### find
```ts
import { find } from 'romast/utils/find'
function find(
node: AST.Node
, predicate: (node: AST.Node) => boolean
): T | undefined
```
#### findAll
```ts
import { findAll } from 'romast/utils/find-all'
function findAll(
node: AST.Node
, predicate: (node: AST.Node) => boolean
): Iterable
```
#### traverseDescendantNodes
```ts
import { traverseDescendantNodes } from 'romast/utils/traverse-descendant-nodes'
function traverseDescendantNodes(node: AST.Node): Iterable
```
#### addHelpers
```ts
import { addHelpers, addHelpersInPlace } from 'romast/utils/add-helpers'
type NullOrNodeWithHelpers =
T extends null
? null
: NodeWithHelpers>
type NodeWithHelpers<
Node extends AST.Node
, Sibling extends AST.Node | null = AST.Node | null
, Parent extends AST.Node | null = AST.Node | null
> =
Node extends AST.Document
? Mixin
>
}>
: Node extends AST.Paragraph
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array<
NodeWithHelpers<
AST.UniversalInlineContent
, AST.UniversalInlineContent
, AST.Paragraph
>
>
}>
: Node extends AST.Section
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
headline: NodeWithHelpers
children: Array<
NodeWithHelpers<
AST.SectionContent
, AST.SectionContent
, AST.Section
>
>
}>
: Node extends AST.Headline
? Mixin
index: null
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array<
NodeWithHelpers<
AST.UniversalInlineContent
, AST.UniversalInlineContent
, AST.Headline
>
>
}>
: Node extends AST.Paragraph
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array<
NodeWithHelpers<
AST.UniversalInlineContent
, AST.UniversalInlineContent
, AST.Paragraph
>
>
}>
: Node extends AST.List
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array>
}>
: Node extends AST.ListItem
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array<
NodeWithHelpers<
AST.UniversalInlineContent
, AST.UniversalInlineContent
, AST.ListItem
>
>
}>
: Node extends AST.Table
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
header: NodeWithHelpers | null
children: Array>
}>
: Node extends AST.TableRowGroup
? Mixin
index: Sibling extends null ? null : number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array>
}>
: Node extends AST.TableRow
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array>
}>
: Node extends AST.TableCell
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array<
NodeWithHelpers<
AST.UniversalInlineContent
, AST.UniversalInlineContent
, AST.TableCell
>
>
}>
: Node extends AST.Footnote
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array<
NodeWithHelpers<
AST.UniversalBlockContent
, AST.UniversalBlockContent
, AST.Footnote
>
>
}>
: Node extends AST.InlineFootnote
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array<
NodeWithHelpers<
AST.UniversalInlineContent
, AST.UniversalInlineContent
, AST.InlineFootnote
>
>
}>
: Node extends AST.Link
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array<
NodeWithHelpers<
AST.UniversalInlineContent
, AST.UniversalInlineContent
, AST.Link
>
>
}>
: Node extends AST.Drawer
? Mixin
index: number
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
children: Array<
NodeWithHelpers<
AST.UniversalInlineContent
, AST.UniversalInlineContent
, AST.Drawer
>
>
}>
: Mixin
index: number | null
previousSibling: NullOrNodeWithHelpers
nextSibling: NullOrNodeWithHelpers
}>
function addHelpers(node: T): NodeWithHelpers
function addHelpersInPlace(node: T): NodeWithHelpers
```
#### removeHelpers
```ts
import { removeHelpers, removeHelpersInPlace } from 'romast/utils/remove-helpers'
function removeHelpers(node: NodeWithHelpers): T
function removeHelpersInPlace(node: NodeWithHelpers): T
```
#### withHelpers
```ts
import { withHelpers, withHelpersInPlace } from 'romast/utils/with-helpers'
function withHelpers(
node: T
, fn: (node: NodeWithHelpers) => U
): U
function withHelpersInPlace(
node: T
, fn: (node: NodeWithHelpers) => U
): U
```