~mplscorwin/ofda

org file data access
skip past properties by default
document the INCLUDE-DRAWERS keyword arg
skip drawers unless :include-drawers is non-null

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~mplscorwin/ofda
read/write
git@git.sr.ht:~mplscorwin/ofda

You can also use your local clone with git send-email.

#Table of Contents

  1. Quick Start
  2. Overview
  3. Emacs Usage
  4. UDFA
  5. LICENSE

#+TITLE ofda - org file data access #+COPYRIGHT 2022 Corwin Brust corwin@bru.st and contributers #+LICENSE GPLv3+

Use an org-file for persistence in shell scripts and other programs.

#Quick Start

./ofda.sh path.to.heading some test to insert
> some text to insert

./ofda.sh path.to.heading
> some text to insert

#Overview

By default data stored in the file "data.org" in the current directory.

Control this by setting "OFDATA" or by suppling the path to an existing file as the first argument to the ofda shell script:

/usr/bin/env OFDATA=some-file.org ./ofda.sh path.to.heading text to insert
# same, given "some-file.org" already exists
./ofda.sh some-file.org path.to.heading text to insert

The next (or first) argument supplies a "query", which searchs for the text of an heading. Multiple headlines can be concatenated with dot (".") to find a headline a specific place in the document hierarchy.

Queries may omit skip sections of the document hierarchy. Given a data.org created per 1, these commands do the same thing:

./ofda.sh path.to.heading
./ofda.sh to.heading
./ofda.sh path.heading

#Emacs Usage

The ofda command can be used interactively within an Emacs session, and will prompt for the name of the org-file and for the headline query, inserting the content document (or from the matched section, if any, given a query) into the current buffer.

When called non-interactively –from elisp– or with a prefix argument, results are sent to standard-output via princ, usually to appear in the echo-area.

#UDFA

ofda [file.org] [ QUERY [[ VALUE ]]]

The ofda shell script provides a convent wrapper for getting and setting data within an org-file from outside of Emacs.

ofda [file.org] [ QUERY [[ VALUE ]]]

Given data.org contains something like:

*path
**to
***heading
value

We can query deeper into the document structure by separating "nested headline" queries using a dot ("."). Using udfa this might look like:

./ofda.sh data.org path.to.heading

The above command will yield:

value

This is roughly equivalent to this shell one-liner:

emacs -Q -lofda \
      --batch '(ofda "data.org" "path.to.heading")'

Additional arguments to the ofda shell script following the query are combined and then used as an insert/replacement value. The headline/hierarchy supplied is created if it does not exist.

Given data.org was created using the 1 example, this will update the content of the "headline" section:

./ofda.sh data.org path.to.heading new-value

After which data.org will contain:

*path
**to
***heading
new-value

These commands are equivalent. Either will append a new headline (titled "headline") within a section called "for" create after (but at the level as) the "to" section, inserting "another value" as the content:

./ofda.sh path.for.heading "another value"
./ofda.sh path.for.heading another value

Resulting in a data-file that looks like:

* path
** to
*** heading
value

** for

*** heading
new value

#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 https://www.gnu.org/licenses/.