org-mode-connection v0.8.8
#+TITLE: org-mode-connection
This package allows to read, write and sync emacs's org-mode files.
It was developed as foundation for [https://github.com/bnankiewicz/organic] - mobile org-mode client written in React Native.
It is designed to work both in mobile and server/desktop environments.
- Installation
#+BEGIN_SRC sh yarn add realm promisify-node org-mode-connection #+END_SRC
- Configuration
** with Node.js
#+name: setup #+BEGIN_SRC js :results output var OrgApi = require('org-mode-connection').OrgApi const realm = require('realm') const promisify = require('promisify-node'); const fsInterface = promisify('fs')
OrgApi.configureFileAccess(fsInterface); OrgApi.configureDb(realm); OrgApi.connectDb(); #+END_SRC
** with React Native #+BEGIN_SRC javascript import OrgApi from 'org-mode-connection'; import RNFS from 'react-native-fs'; import Realm from 'realm';
OrgApi.configureFileAccess(RNFS); OrgApi.configureDb(Realm); OrgApi.connectDb(); #+END_SRC
- Usage
** Example
#+BEGIN_SRC js :results output :noweb yes const query = async() => { await OrgApi.clearDb() await OrgApi.addFile('~/org/organizer.org') const res = await OrgApi.getAllFilesAsPlainObject() console.log(res) } query() #+END_SRC
* Parsing node content #+name: parse-example-content #+BEGIN_SRC js :results output code :noweb yes //import { NodeContentParser } from "org-mode-connection"; const NodeContentParser = require('org-mode-connection').NodeContentParser const res = NodeContentParser(" this is bold* and this /italic/\nnext line"); console.log("// Parsed lines:\n", res, "\n") console.log("// Content of the first line:\n", res0.content) #+END_SRC
#+BEGIN_SRC js // Parsed lines: [ { type: 'regularLine', content: [ Object, Object, Object, Object, Object ] }, { type: 'regularLine', content: [ Object ] } ]
- Api ** addFile(/title/) Creates empty file in database.
=Arguments=:
- title: string - New file title
=Results=:
Promise
** addNodes(/nodes/, /insertPosition/, /externalChange/, /returnAddedNodes/) Add nodes to the tree of nodes
=Arguments=:
- nodes: [#PlainOrgNode][]
- insertPosition: [#InsertPosition]
- externalChange: boolean
- returnAddedNodes: boolean
=Results=:
Promise<[#PlainOrgNode][]>
** clearDb() Clears Database.
=Results=:
Promise
** configureDb(/realm/) Configure database.
=Arguments=:
- realm: [#Realm] - Realm object
=Results=:
void
** configureFileAccess(/fsIterface/) =Arguments=:
- fsIterface: [#FsInterface] - Promisified file access interface
=Results=:
void
** connectDb() Connect database
=Results=:
Promise
** createFileFromString(/name/, /lines/) Create file from array of strings.
=Arguments=:
- name: string - The name of new file
- lines: string[] - List of string raw lines
=Results=:
Promise
** deleteFileById(/fileId/) Delete file from database.
=Arguments=:
- fileId: string - File id
=Results=:
Promise
** deleteNodeById(/nodeId/) Deletes node.
=Arguments=:
- nodeId: string
=Results=:
Promise
** getAgendaAsPlainObject(/timeRange/, /defaultWarningPeriod/) Returns agenda as plain object
=Arguments=:
- timeRange: [#TimeRange]
- defaultWarningPeriod: number
=Results=:
Promise<[#PlainAgenda]>
** getAllFilesAsPlainObject() Returns all OrgFiles as plain objects
=Results=:
[#PlainOrgFile][]
** getAncestorsAsPlainObject(/nodeId/) Returns all ancestors of node.
=Arguments=:
- nodeId: string
=Results=:
Promise<[#PlainOrgNode][]>
** getExternallyChangedFiles() Returns ids of externally changed files
=Results=:
Promise<[#ExternalFileChange][]>
** getFileAsPlainObject(/id/) Returns file and its nodes data as plain object.
=Arguments=:
- id: string - File id
=Results=:
Promise<[#PlainOrgFile]>
** getObjects(/model/, /filter/) Return raw RealmResults object
=Arguments=:
- model: undefined - Realm model
- filter: string - Realm filter string
=Results=:
Promise<[#RealmResults]>
** getOrCreateNodeByHeadline(/targedNode/) Gets node by headline. If node doasnt exists it is created.
=Arguments=:
- targedNode: { fileId: string, headline: string }
=Results=:
Promise<[#PlainOrgNode]>
** getRelatedNodes(/nodeId/) Returns ancestors and descendants
=Arguments=:
- nodeId: string
=Results=:
Promise<[#PlainOrgNode][]>
** getTagsAsPlainObject() Returns list of all tags
=Results=:
Promise<string[]>
** getTocs() Returns all files with their child nodes
=Results=:
Promise<[#Tocs]>
** importFile(/filepath/) Imports external file
=Arguments=:
- filepath: string
=Results=:
Promise
** search(/searchQuery/) Search
=Arguments=:
- searchQuery: [#SearchQuery]
=Results=:
Promise
** syncDb() Sync all files
=Results=:
Promise
** syncFile(/id/) Syncs file
=Arguments=:
- id: any - file id
=Results=:
Promise
** updateFile(/id/, /changes/) Merges prop to file object
=Arguments=:
- id: string - File id
- changes: Object - New file props to merge
=Results=:
Promise
** updateNodeById(/id/, /changes/) Merges props to node object
=Arguments=:
- id: string - Node id
- changes: Object - New node props to merge
=Results=:
Promise
- Types
** PlainOrgFile :PROPERTIES: :CUSTOM_ID: PlainOrgFile :END: #+BEGIN_SRC typescript type PlainOrgFile = { id: string; name: string; size: string; ctime: string; mtime: string; path: string; title: string; description: string; metadata: string; category: string; lastSync: string; isChanged: boolean; isConflicted: boolean; }; #+END_SRC
** PlainOrgNode :PROPERTIES: :CUSTOM_ID: PlainOrgNode :END: #+BEGIN_SRC typescript type PlainOrgNode = { id: string; level: number; position: number; headline: string; content?: string; fileId: string; category?: string; todo?: string; priority?: string; drawers: string; tags: string[] timestamps: PlainOrgTimestamp[] } #+END_SRC
** PlainOrgTimestamp :PROPERTIES: :CUSTOM_ID: PlainOrgTimestamp :END: #+BEGIN_SRC typescript type PlainOrgTimestamp = { type: "active" | "inActive" | "scheduled" | "deadline"; date: string; dateRangeEnd: string; dateRangeWithTime: boolean; dateWithTime: boolean; warningPeriod: string; repeater: string; } #+END_SRC
** PlainAgenda :PROPERTIES: :CUSTOM_ID: PlainAgenda :END: #+BEGIN_SRC typescript type NodeTimestamp = { type: string; nodeId: string; }
type PlainAgenda = { nodes: PlainOrgNodesDict; agendaItems: NodeTimestamp[]; dayAgendaItems: NodeTimestamp[]; }; #+END_SRC
** SearchQuery :PROPERTIES: :CUSTOM_ID: SearchQuery :END: #+BEGIN_SRC typescript type SearchQuery = { searchTerm: string; todos: any[]; tags: any[]; priorioty: string; isScheduled: boolean; hasDeadline: boolean; }; #+END_SRC
** FsInterface :PROPERTIES: :CUSTOM_ID: FsInterface :END: #+BEGIN_SRC typescript type FsStat = { mtime: string; ctime: string; name: string; size: string; }
interface FsInterface { write(): Promise; exists(path: string): Promise; read(path: string): Promise<string[]>; stat(path: string): Promise; } #+END_SRC ** ExternalFileChange :PROPERTIES: :CUSTOM_ID: ExternalFileChange :END: #+BEGIN_SRC typescript type ExternalFileChange = { id: string; mtime: string; }; #+END_SRC
** InsertPosition :PROPERTIES: :CUSTOM_ID: InsertPosition :END: #+BEGIN_SRC typescript type InsertPosition = { fileId: string; nodeId?: string; headline?: string; } #+END_SRC
** TimeRange :PROPERTIES: :CUSTOM_ID: TimeRange :END: #+BEGIN_SRC typescript type TimeRange = { start: string; end: string; }; #+END_SRC
** Tocs :PROPERTIES: :CUSTOM_ID: Tocs :END: #+BEGIN_SRC typescript type Tocs = { ids: { fileId: string: string[] }; data: PlainOrgNodesDict; }; #+END_SRC
** PlainOrgNodesDict #+BEGIN_SRC typescript type PlainOrgNodesDict = { nodeId: string: PlainOrgNode }; #+END_SRC
** Realm :PROPERTIES: :CUSTOM_ID: Realm :END: RealmJs object.
- License
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.