skip past properties by default
document the INCLUDE-DRAWERS keyword arg
skip drawers unless :include-drawers is non-null
#+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.
./ofda.sh path.to.heading some test to insert
> some text to insert
./ofda.sh path.to.heading
> some text to insert
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
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.
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
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/.