* lisp/ob-core.el (org-babel-expand-noweb-references--cache):
(org-babel-expand-noweb-references--cache-buffer): New variables
storing info cache.
(org-babel-expand-noweb-references): Make use of global info cache to
avoid extra parsing. Use `cl-macrolet' instead of defining transient
lambda functions on every call.
The Emacs doc string convention is to document values as-is when that
is clear, and surrounded by `single quotes' otherwise. For example, a
doc string "(a b c)" stands for a list of symbols, and the doc string
"`a'" stands for a single symbol. The doc string "\\=`a" is typically
not correct for that single symbol, because that is equivalent to
"(quote a)" and the typical intent is to talk about the symbol, not
about the Lisp quoting construct. One needs "\\=`X" only when talking
about something intended to be equivalent to "(quote X)", as in the
doc string "(provide \\='org-xyz)".
As mentioned in 2e36ac2ac (Merge single quote fixes from Emacs's
master, 2022-07-24), this merge is keeping Org main's side of
org-babel-lua-read-string and org-agenda-sorting-strategy rather than
the variant introduced in the Emacs repo that's now in bugfix.
Note that for org-agenda-sorting-strategy docstring I think it'd
probably be preferable to change main's
\\='(time-up category-keep priority-down)
to a bare
(time-up category-keep priority-down)
but, at least for this merge, I'm sticking to choosing between the
variables that are in one of the sides.
* lisp/ox-publish.el (org-publish-find-property):
* lisp/ox-html.el (org-html--unlabel-latex-environment):
* lisp/org-table.el (org-table-collapse-header):
* lisp/org-plot.el (org--plot/prime-factors):
* lisp/org-agenda.el (org-agenda--mark-blocked-entry):
(org-agenda-set-restriction-lock):
* lisp/ob-lua.el (org-babel-lua-read-string):
* lisp/ob-julia.el (org-babel-julia-evaluate-external-process):
(org-babel-julia-evaluate-session):
* lisp/ob-core.el (org-babel-default-header-args): Fix
quoting in doc strings. In code examples, the ' character is
quoted with \\=, and regularize 'foo to `foo', and quote strings
like "foo" instead of 'foo'.
Audit quoting the quote character in doc strings
bbf389ea6deab229ba18dc519fe712ec982609d1
Lars Ingebrigtsen
Fri Apr 22 16:17:22 2022 +0200
[km] Org's bugfix branch is currently receiving commits from emacs-28,
but this commit comes from Emacs's master branch. I'm porting it
because it has conflicts with bugfix's 01b0fb14b (Backport from
main: Escape single left quotes in docstrings, 2022-07-24) and
only touches docstrings.
* lisp/ob-core.el (org-babel-default-header-args): Provide an example
illustrating one benefit of using closures as default header
arguments. Additionally, explain how to provide the same type of
header argument multiple times in the default alist.
* lisp/ob-core.el: Make sure that
`org-babel-temporary-stable-directory' is set to non-nil non-existent
directory. Non-existent directory is required to avoid clashes when
multiple Emacs processes are running.
Fixes https://yhetil.org/emacs-devel/87sfnfhm6v.fsf@yandex.com
* lisp/ob-core.el (org-babel-temporary-stable-directory): New variable
holding a temporary directory name that does not change between Emacs
sessions.
(org-babel-remove-temporary-stable-directory): New function removing
`org-babel-temporary-stable-directory' on Emacs shutdown.
(org-babel-temp-stable-file): Generate stable temporary file name for
object storage. The file name is constant for equal objects.
(org-babel-execute-src-block): Explicitly identify that if the result
is cached.
* lisp/ob-gnuplot.el (org-babel-gnuplot-process-vars): Make use of
`org-babel-stable-file' to make expanded body stable with respect to
:var assignments.
Fixes https://orgmode.org/list/87mtn1o5mn.fsf@ucl.ac.uk
Emacs now advises using "website" (instead of "homepage") and
consequently to use the "URL" comment header instead of "Homepage".
* README:
* README_ELPA:
* doc/org-guide.org (Creating Footnotes):
* doc/org-manual.org (Creating Footnotes):
* etc/styles/README (URL): Prefer "website" to "homepage".
* lisp/*.el:
* mk/org-fixup.el: Replace the "Homepage" header comment with "URL".
* lisp/ob-core.el (org-babel-default-header-args):
* lisp/ob-julia.el (org-babel-julia-evaluate-external-process):
(org-babel-julia-evaluate-session):
* lisp/ob-lua.el (org-babel-lua-read-string):
* lisp/ob-table.el (org-sbe):
* lisp/oc-basic.el (org-cite-basic--shorten-names):
* lisp/org-agenda.el (org-agenda-sorting-strategy):
(org-agenda--mark-blocked-entry):
(org-agenda-set-restriction-lock):
* lisp/org-fold-core.el (org-fold-core--specs):
(org-fold-core-remove-folding-spec):
(org-fold-core-get-folding-spec):
(org-fold-core--isearch-overlays):
* lisp/org-plot.el (org--plot/prime-factors):
* lisp/org-table.el (org-table-collapse-header):
* lisp/org.el (org-special-ctrl-o):
(org-latex-to-html-convert-command):
* lisp/ox-html.el (org-html--unlabel-latex-environment):
* lisp/ox-publish.el (org-publish-find-property):
Use \\=' when there's a need for a single left quote in a docstring.
The emacs-29 byte compiler complains about such usage.
* ob-core.el (org-babel-merge-params): Specifying the symbol 'attach`
or string "'attach" as the value of the `:dir' header now functions as
":dir (org-attach-dir nil t) :mkdirp t".
(org-babel-result-to-file): Optional TYPE argument accepts symbol
'attachment to fixup up paths under `(org-attach-dir)' and use the
link type "attachment:" when that is detected.
(org-babel-insert-result): Pass symbol `attachment' as TYPE to
`org-babel-result-to-file'.
* org-attach.el (org-attach-dir): Added autoload header to simplify
dependencies necessary to support this feature (called in
`org-babel-merge-params').
* test-ob.el (test-ob-core/dir-attach): Added unit test for the new
attach feature.
* lisp/ob-core.el (org-babel-expand-noweb-references): Add support for
`noweb-prefix' header argument, to not repeat the prefix characters
when expanding a noweb reference.
(org-babel-common-header-args-w-values):
(org-babel-safe-header-args): Add `noweb-prefix' value.
* doc/org-manual.org: Document `noweb-prefix' babel header argument.
* etc/ORG-NEWS: Document `:noweb-prefix'.
* lisp/org-element.el (org-element-with-disabled-cache): New macro.
(org-element-greater-elements): Add new org-data element. It
functions like a virtual headline containing the whole buffer. The
org-data properties are like headlie properties, but according to the
top-level drawer. org-data's category is the buffer's category as
defined by top-level property drawer, #+CATEGORY keyworsd, and the
buffer file name.
(org-element--cache-element-properties, org-element-set-element): New
variable containing properties to be transferred when updating changed
element in cache in `org-element-set-element'.
(org-element--get-node-properties): Allow parsing node propreties in
top-level drawer when new optional argument is passed. Respect
PROPERTY+ syntax.
(org-element--get-global-node-properties): New function. It returns
node properties for top-level property drawer.
(org-element-org-data-parser, org-element-org-data-interpreter):
Implement the new org-data element.
(org-element-headline-parser, org-element-section-parser): Add new
:robust-begin and :robust-end
properties delimiting safe changes that do not modify headline
element.
(org-element--list-struct): Fix cache update when adding a headline
inside list.
(org-element--current-element): Implement cache support. Record
parsing mode (:mode) and parsing granularity (:granularity) in the
element properties.
(org-element-parse-buffer, org-element--next-mode): Support new
org-data element.
(org-element--parse-elements): Record parsing granularity in the
returned tree
(org-element-use-cache): Enable cache by default.
(org-element-cache-persistent): New variable controlling cache
persistance across sessions. Enabled by default.
(org-element--cache-self-verify,
org-element--cache-self-verify-frequency,
org-element--cache-diagnostics, org-element--cache-map-statistics,
org-element--cache-map-statistics-threshold,
org-element--cache-diagnostics-level,
org-element--cache-diagnostics-ring,
org-element--cache-diagnostics-ring-size): New variables controlling
cache diagnostics and self-diagnostics. Greatly simplifies cache
debugging.
(org-element--cache, org-element--cache-sync-requests,
org-element--cache-sync-timer): Make cache buffer-local by default.
(org-element--headline-cache): Implement separate cache storing only
headlines and inlinetasks.
(org-element--cache-size, org-element--headline-cache-size): New
variables containing cache sizes. This is much faster than
`avl-tree-size'.
(org-element--cache-sync-requests): Update docstring explaning the
request list structure.
(org-element--cache-sync-keys-value): New variable replacing
`org-element--cache-sync-keys' hash table. The hash table was not
reliable because it was using elements as keys. Upon any cached
element update/shift, the keys were invalidated making cache ordering
incorrect and breaking the cache badly. Now, the cache keys are
stored as :org-element--cache-sync-key element property and the new
variable stores marker value indicating the current sync request
cycle. See `org-element--cache-key' for more details.
(org-element--cache-change-tic): New variable controlling buffer
modification count that is registered in cache. This variable allows
catching "stealth" edits.
(org-element--cache-non-modifying-commands): New variable listing
commands that will not be slown down if we fill cache on the fly.
(org-element--request-key, org-element--request-beg,
org-element--request-end, org-element--request-offset,
org-element--request-parent, org-element--request-phase): New macros.
They improve code readability (especially when using nameless-mode).
(org-element--format-element, org-element--cache-log-message,
org-element--cache-warn): New macros implementing generic logging
functionality.
(org-element--cache-key): Add section and org-data element support.
Change cache key storage from hash map to :org-element--cache-sync-key
element property + `org-element--cache-sync-keys-value'. We use the
latter to group all the cache keys during a single cache request
sequence. Once sync request is fully complete, the
`org-element--cache-sync-keys-value' is updated making all the old
sync keys obsolete (they will still be store as element properties).
(org-element--headline-cache-root): New function returning headline
cache root.
(org-element--cache-active-p): Prevent cache updates when
`inhibit-modification-hooks' is non-nil, unless non-nil optional
argument is provided.
(org-element--cache-find): Share cache between indirect buffers and
the base buffer. We have to do it because after-change hooks for
indirect buffer are not called in the base buffer and vice versa. Add
support for section and org-data elements.
(org-element--cache-put): Implement new approach for cache key
storage. Add diagnostics. Indicate cached elements using :cached
element property. Support cache size calculation.
(org-element--cache-remove): Invalidate parent contents when removing
element. Support cache size calculation. Detect cache corruption due
to misordered elements.
(org-element--cache-shift-positions): Support :robust-begin and
:robust-end element properties.
(org-element--cache-sync): Add diagnostics. Add detailed comments.
Prevent slowdown when large cache chunks need to be deleted forcing
O(N) complexity cutoff. In phase 2, fix cases when next request
contains deleted cache key. In phase 2, fix scenario when newly
inserted element intersects with existing elements in cache. In phase
2, detect obsolete parents removed from cache.
(org-element--open-end-p): New function checking if an element can
have blank lines right after its :contents-end.
(org-element--parse-to): Do not alter match data. Process complex
parsing mode changes correctly. Support headlines in cache. Support
org-data parsing. Add detailed comments. Add diagnostics.
(org-element--cache-sensitive-re): Make list lines sensitive.
(org-element--cache-change-warning): Update docstring. Now, the
variable can have t, nil, and number values. Numbers are used to
provide more details about changed headlines.
(org-element--cache-before-change, org-element--cache-after-change):
Handle headline hierarchy. Properly handle cache in indirect
buffers.
(org-element--cache-after-change): Update docstring clarifying the
return values. Add special handling for headline and org-data
elements updating them in-place instead of removing together with the
whole contents when possible. Use :robust-begin/:robust-end element
properties to detect robust changes.
(org-element--cache-submit-request): Add detailed comments. Correctly
handle cache in indirect buffers. Delegate element modifications to
`org-element--cache-for-removal'.
(org-element--cache-verify-element): New function for cache
self-verification.
(org-element--cache-persist-before-write,
org-element--cache-persist-before-read,
org-element--cache-persist-after-read): Implement cache persistance.
(org-element-cache-reset): Correctly handle cache in indirect
buffers. Support cache persistance. Support new cache size
calculation and new cache key schema.
(org-element-cache-map): New function analagous to `org-element-map',
but much faster. The function overperforms org-ql written by Adam
Porter aka alphapapa [1] and reuses some ideas from there (namely,
fast element skipping via regexps).
[1] https://github.com/alphapapa/org-ql/
(org-element-at-point): The returned elements are now guaranteed to
have correct parents up to org-data. New optional argument
CACHED-ONLY limits element search to current cache---if element is not
in cache and current command is not in cache
`org-element--cache-non-modifying-commands', the cache is not updated
and the function returns nil. Also, support cache verification.
(org-element-at-point-no-context): New function. It is analogous of
older `org-element-at-point' with no guarantee that :parent properties
are correct beyond direct parent heading. This function does not
update cache and can be useful when cache updates should be avoided
for performance reasons.
* lisp/ob-core.el (org-babel-where-is-src-block-result): Support
section and org-data elements in cache.
* lisp/org-macro.el (org-macro-replace-all,
org-macro--find-keyword-value): Support org-element-cache.
* lisp/org-table.el (orgtbl-to-generic): Support org-element-cache.
* lisp/org.el (org-mode): Add cache persistance.
(org-up-element): Preserve old behaviour when error is returned for
section and org-data element.
*
testing/lisp/test-org-archive.el (test-org-archive/update-status-cookie):
Fix test when cache is active.
* testing/lisp/test-org-colview.el (test-org-colview/columns-update):
Fix test.
* testing/lisp/test-org-element.el (test-org-element/extract-element):
Add suport for new org-data element.
* testing/lisp/test-org-element.el (test-org-element/parent-property):
Fix equality check. Parents returned by cache and `org-element-map'
may not be `eq' now. Just `equal'.
* testing/lisp/test-org-element.el (test-org-element/context): Support
section and headline parents.
* lisp/ob-core.el (org-babel-eval-headers): Fix elements ordering.
(org-babel-merge-params): Tiny refactoring.
This fixes the test `test-ob-lob/call-with-header-arguments' that
fails after 9f1507bdd.
* lisp/ob-core.el (org-babel-default-header-args): Document ability to
use closures.
(org-babel-eval-headers): New function to generate header arguments,
which adds the ability to evaluate closures during source block
execution or export.
(org-babel-merge-params): Only evaluate closures when we have our
final list of headers.
* lisp/ob-core.el (org-babel-disassemble-tables): Avoid length> for
compatibility with Emacs versions before 28.
length> and friends were added to Emacs in 0f790464d5 (Add new
predicates for sequence lengths, 2020-12-27), which hasn't yet made it
into a release.
* lisp/ob-core.el (org-babel-disassemble-tables,
org-babel-gnuplot-process-vars): Use `proper-list-p' check instead of
`listp'.
(org-babel-disassemble-tables): Check list length before trying to
remove hline from a table assignment.
* testing/lisp/test-ob.el (test-ob/cons-cell-as-variable): Add the
test.
* lisp/ob-core.el (org-babel-default-header-args): Document ability to
use functions.
(eval-default-headers): New function to generate default header
arguments, which adds the ability to evaluate function arguments at
runtime.
(org-babel-get-src-block-info): Use new header argument evaluate
function when retreiving src block info.
* lisp/ob-exp.el (org-babel-exp-src-block): Must use new
eval-default-headers when exporting as well.
The closures are evaluated at runtime.
The commit d4b739fbf2 added the "none" header argument but didn't
add it to the `org-babel-insert-result' documentation string. Put it
in the doc string so that users can discover it.
Signed-off-by: Yasushi SHOJI <yashi@spacecubics.com>
* lisp/ob-core.el (org-babel-expand-noweb-references): Fix order when
searching for named babel blocks so that blocks in the current buffer
are always found first. This fixes a bug where stale versions of
blocks that have been ingested into the library of babel were being
preferentially tangled instead of newly modified versions from the
current buffer.
* lisp/ob-core.el (org-babel-edit-distance): Rename function
`org-string-distance' and move it to "org-compat.el".
(org-babel-check-src-block): Use `org-string-distance' instead.
* lisp/org-compat.el: Add `org-string-distance' for a future
deprecation in favor of `string-distance'.
* lisp/ob-core.el (org-babel-result-end): Alloow the result to end
into a LaTeX environment.
By adding latex-enviroment to the possible results types, a much
richer experience is possible for backends that can produce
LaTeX-formatted maths as their results (for example: Calc, Julia with
Latexify, Python with SymPy, Octave with symbolic). This is superior
to a LaTeX export block as LaTeX environments can be (1) rendered
inline, and (2) better used in non-LaTeX export formats (e.g. HTML
with MathJax). Without this, backends can output a LaTeX environment,
but new results will be added in front instead of replacing the
environment.
Porting from Emacs's master to Org's maint branch has been on hold
leading up to the Emacs 27.2 release to avoid any required fixup syncs
carrying those commits into the emacs-27 branch. This merge brings
those changes into master. The km/from-emacs-master branch should be
merged to maint when Emacs 27.2 has been released (assuming Org 9.5
hasn't been released, in which case maint will be tracking 9.5.x and
already include these changes).
* lisp/ob-comint.el (org-babel-comint-in-buffer)
(org-babel-comint-with-output): Use `declare`.
* lisp/ob-core.el (org-babel-map-src-blocks): Use `declare`.
(org-babel-result-cond): Simplify edebug spec.
* lisp/org-clock.el (org-with-clock-position, org-with-clock):
* lisp/org-agenda.el (org-agenda-with-point-at-orig-entry):
* lisp/ob-tangle.el (org-babel-with-temp-filebuffer): Use `declare`.
Use `declare` instead of `def-edebug-spec` in most places
f8dbefbaa59bb17dd4a2dfa4d9ff560c46785792
Stefan Monnier
Fri Feb 12 16:08:01 2021 -0500
* lisp/ob-core.el (org-babel--string-to-number): Put hyphen last in
alternative.
* lisp/org-agenda.el (org-agenda-filter): Escape '+' correctly.
Follow good regexp practice
46394dff7f01e7fe4af06a6c344e151af5c3eef4
Mattias Engdegård
Fri Dec 18 14:35:09 2020 +0100
* doc/org-manual.org (Type): Document empty vector argument for
file-desc.
* etc/ORG-NEWS (New argument for ~file-desc~ babel header): Add entry
to NEWS.
* lisp/ob-core.el (org-babel--file-desc): Add new function to evaluate
file description value.
(org-babel-execute-src-block): Correctly evaluate file description
when executing src block.
(org-babel-insert-result): Correctly evaluate file description value
when inserting the result of src block execution into the buffer.
* testing/lisp/test-ob.el (test-ob/file-desc-header-argument): Add
test case for new behavior.
* lisp/ob-core.el (org-babel-expand-noweb-references): Don't anchor
noweb regexp at start of line to allow multiple matches per line.
* testing/lisp/test-ob-tangle.el (ob-tangle/multiple-noweb-in-line):
Add test.
This fixes a regression introduced by c1aed9f80 (ob-core: Refactor
`org-babel-expand-noweb-references', 2020-01-12), which was part of
the 9.4 release.
Reported-by: Tom Gillespie <tgbugs@gmail.com>
Ref: https://orgmode.org/list/CA+G3_PO2yO1jMMpdrkc39BGQQ2eU5X4FzTEJVotjDJo-50dsqQ@mail.gmail.com
* lisp/ob-core.el (org-babel--expand-body): New function.
(org-babel-check-confirm-evaluate):
(org-babel-execute-src-block): Use org-babel--expand-body.
As of 727c6d7fe (lisp/ob-core.el: org-babel-check-confirm-evaluate
strip coderefs, 2020-09-04), org-babel-check-confirm-evaluate and
org-babel-execute-src-block use the same logic to expand the body and
strip coderefs. Move that code to a helper function.
This patch is functionally equivalent to the patch originally proposed
by Tom Gillespie at
https://orgmode.org/list/CA+G3_PNi3uMvBiWgBdKuC3C6VJt1T1j-RKH43LRqYbr+4NS8ZA@mail.gmail.com
* lisp/ob-core.el (org-babel-check-confirm-evaluate): strip coderefs
before passing the body of the block to org-confirm-babel-evaluate
using the same let block as is used in org-babel-execute-src-block.
* lisp/ob-core.el (org-babel-result-to-file): Use
`buffer-base-buffer' so that `buffer-file-name' returns correct
results in indirect buffers too.
See <https://orgmode.org/list/87eeos3w7v.fsf@localhost>
TINYCHANGE
* lisp/ob-core.el (org-babel-import-elisp-from-file): Don't try to
convert empty file to a table.
* testing/lisp/test-ob.el (test-ob/import-elisp-from-file): Add tests.
If org-babel-import-elisp-from-file is called with an empty file
(which many ob- libraries do when there are no results), feeding that
to org-table-import leads to a beginning-of-buffer error. Before
14878f3f9 (ob-core: Display warning on failure to read results,
2020-05-21), this error was hard to notice because, after catching it,
it was reported as a quickly buried message. After that commit, it is
displayed as a warning, which is not appropriate for the common and
unproblematic case of empty results.
Avoid the warning by only doing the table conversion if the file has
content. Another option would be to do the table conversion but add a
beginning-of-buffer arm to the surrounding condition-case. However,
that risks swallowing other sources of that error.
Reported-by: Colin Baxter <m43cap@yandex.com>
<https://orgmode.org/list/878se3nhbj.fsf@yandex.com>
* ob-core.el (org-babel-execute-src-block): Source code block header
argument `:file-mode' can set file permissions if `:file' argument is
provided.
(org-babel-common-header-args-w-values): Add `:file-mode' to common
header arguments.
TINYCHANGE
