{"id":13861916,"url":"https://github.com/jingtaozf/literate-elisp","last_synced_at":"2025-04-15T12:27:08.312Z","repository":{"id":43045882,"uuid":"158058448","full_name":"jingtaozf/literate-elisp","owner":"jingtaozf","description":"Load Emacs Lisp code blocks from Org files","archived":false,"fork":false,"pushed_at":"2025-01-03T01:33:53.000Z","size":2447,"stargazers_count":48,"open_issues_count":3,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-15T12:27:04.944Z","etag":null,"topics":["elisp","emacs","literate","literate-programs","org","org-mode"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jingtaozf.png","metadata":{"files":{"readme":"readme.org","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-11-18T07:01:17.000Z","updated_at":"2025-03-25T17:46:21.000Z","dependencies_parsed_at":"2024-04-13T16:00:24.302Z","dependency_job_id":null,"html_url":"https://github.com/jingtaozf/literate-elisp","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingtaozf%2Fliterate-elisp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingtaozf%2Fliterate-elisp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingtaozf%2Fliterate-elisp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingtaozf%2Fliterate-elisp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jingtaozf","download_url":"https://codeload.github.com/jingtaozf/literate-elisp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249070719,"owners_count":21207885,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elisp","emacs","literate","literate-programs","org","org-mode"],"created_at":"2024-08-05T06:01:32.869Z","updated_at":"2025-04-15T12:27:08.277Z","avatar_url":"https://github.com/jingtaozf.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"# -*- encoding:utf-8 Mode: POLY-ORG;  -*- --- \n#+Startup: noindent\n#+PROPERTY:    header-args        :results silent   :eval no-export   :comments org\n#+OPTIONS:     num:nil toc:nil todo:nil tasks:nil tags:nil\n#+OPTIONS:     skip:nil author:nil email:nil creator:nil timestamp:t\n#+INFOJS_OPT:  view:nil toc:nil ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js\n#+PROPERTY: literate-lang elisp\n#+PROPERTY: literate-load yes\n\n[[https://melpa.org/#/literate-elisp][file:https://melpa.org/packages/literate-elisp-badge.svg]]\n[[https://stable.melpa.org/#/literate-elisp][file:https://stable.melpa.org/packages/literate-elisp-badge.svg]]\n[[https://travis-ci.com/jingtaozf/literate-elisp][file:https://travis-ci.com/jingtaozf/literate-elisp.svg?branch=master]]\n[[https://github.com/jingtaozf/literate-elisp/actions][file:https://github.com/jingtaozf/literate-elisp/workflows/Continous%20Integration/badge.svg]]\n\n* Table of Contents                                                   :TOC:\n- [[#introduction][Introduction]]\n- [[#tutorial][Tutorial]]\n  - [[#install-polymode-in-emacs][install Polymode in Emacs]]\n  - [[#install-literate-elisp][install literate-elisp]]\n  - [[#how-to-insert-code-block-quickly][how to insert code block quickly]]\n  - [[#load-an-org-file][load an org file]]\n  - [[#byte-compile-an-org-file][byte compile an org file]]\n  - [[#a-new-code-block-header-argument-load][a new code block header argument ~load~]]\n  - [[#compatibility-with-other-libraries][compatibility with other libraries]]\n    - [[#support-for-emacs-lisp-refs][support for Emacs Lisp-Refs]]\n    - [[#support-for-library-helpful][support for library helpful]]\n- [[#faq][FAQ]]\n  - [[#what-can-i-do-when-it-failed-to-load-some-file][What can I do when it failed to load some file]]\n  - [[#can-i-use-autoload-for-a-elisp-routine-in-an-org-file][Can I use =autoload= for a Elisp routine in an org file?]]\n- [[#demo-routines][demo routines]]\n  - [[#a-demo-macro][a demo macro]]\n- [[#a-demo-emacs-configuration][a demo Emacs configuration]]\n  - [[#a-demo-configuration][a demo configuration]]\n    -  [[#enable-org-mode-for-org-files][enable org mode for org files]]\n  - [[#load-this-org-file-in-emacs][load this org file in .emacs]]\n  - [[#packages-written-by-literate-elisp][packages written by literate-elisp]]\n- [[#test][Test]]\n  - [[#introduction-1][Introduction]]\n  - [[#test-macro-aif][test macro aif]]\n  - [[#test-org-mode-configuration][test org mode configuration]]\n- [[#copyright-and-license][Copyright and license]]\n\n* Introduction\n[[https://github.com/jingtaozf/literate-elisp][literate-elisp]] is an Emacs lisp library to provide an easy way to use [[http://www.literateprogramming.com/][literal programming]] in Emacs lisp.\n\nIt extends the Emacs [[https://www.gnu.org/software/emacs/manual/html_node/elisp/How-Programs-Do-Loading.html#How-Programs-Do-Loading][load]] mechanism so Emacs can load [[https://orgmode.org/manual/Working-with-source-code.html#Working-with-source-code][org files]] as lisp source files directly.\n\nThe implementation details of [[https://github.com/jingtaozf/literate-elisp][literate-elisp]] is in file [[./literate-elisp.org]] ([[./literate-elisp.pdf][pdf version]]).\n\nThis library export an Emacs Lisp function ~literate-elisp-load~ \nand this function can load Emacs Lisp codes in all Emacs Lisp code blocks \nsurrounded by ~#+begin_src elisp~ and ~#+end_src~ in an org file directly.\n\nFor example, if you have an org file and it contains such Emacs Lisp code block:\n#+BEGIN_EXAMPLE\n   ,#+BEGIN_SRC elisp :load yes\n   (defun test ()\n    (message \"this is a test from org file.~%\"))\n   ,#+END_SRC\n#+END_EXAMPLE\n\nThen you can load this org file like this:\n#+BEGIN_SRC elisp :load no\n(load \"~/projects/literate-elisp/literate-elisp.el\")\n(literate-elisp-load \"test.org\")\n#+END_SRC\nNow the Emacs Lisp function ~test~ is ready to use,\nand you can jump to the definition of ~test~ in the org file by using Emacs library [[https://github.com/emacs-mirror/emacs/blob/master/lisp/emacs-lisp/find-func.el][find-func]] directly\nwithout tangling them to an Emacs Lisp file(.el).\n\nYou can also open an org file by [[https://polymode.github.io/][polymode]] when edit, which will switch Emacs Lisp code block to Emacs Lisp mode.\n\nSo you will have a perfect literate environment which can write Emacs Lisp codes in an org file, and\nload it directly without tangling an org file to an Emacs Lisp file.\nEmacs lisp's source code editing and navigation feature work well to this org file.\n\nThis library contains the following files:\n- [[./literate-elisp.org]] \\\\ \n  The implementation and documentation of literate Emacs Lisp reader.\n- [[./literate-elisp.el]] \\\\\n  The tangled codes of literate Emacs Lisp reader, generated from [[./literate-elisp.org]].\n- [[./literate-elisp.pdf]] \\\\\n  The weaved documentation, generated from [[./literate-elisp.org]] by org mode's [[https://orgmode.org/manual/Triggering-publication.html#Triggering-publication][publish feature]].\n- [[./readme.org]] \\\\\n  This file contains introduction and demo codes for how to do literate Emacs Lisp in an org file.\n- [[./.travis.yml]] \\\\\n  The config file used by Web service [[https://travis-ci.com/jingtaozf/literate-lisp][travis ci]] to test this library.\n\n* Tutorial\n** install Polymode in Emacs\nThe org file can open as [[https://polymode.github.io/][polymode]],the following Emacs lisp scripts should add in ~.emacs~.\n#+BEGIN_SRC elisp :load no\n(use-package poly-org\n    :ensure t)\n#+END_SRC\n** install literate-elisp\n~literate-lisp~ is available on the two major ~package.el~ community maintained repos - [[https://stable.melpa.org/#/literate-elisp][MELPA Stable]] and [[https://melpa.org/#/literate-elisp][MELPA]].\nYou can install ~literate-elisp~, or more commonly a specific ~literate-elisp~, interactively\n#+BEGIN_SRC text\nM-x package-install [RET] literate-elisp [RET]\n#+END_SRC\nOr you can install it from source directly\n#+BEGIN_SRC elisp :load no\n(load \"~/projects/literate-elisp/literate-elisp.el\")\n#+END_SRC\n\n** how to insert code block quickly\nPlease have a look of the section [[./literate-elisp.org#how-to-insert-code-block-in-org-file][How to insert code block in org file]].\n** load an org file \n\nTo load an org file, we can use Emacs interactive command ~literate-elisp-load~.\n\nFor example, This org file can load directly with the following code.\n#+BEGIN_SRC elisp :load no\n(literate-elisp-load \"readme.org\")\n#+END_SRC\n\nIf you want to load an org file with a Emacs command, please press \"Alt-X\" and type ~literate-elisp-load-file~. \n\nIf you want to load an org file in batch mode, please use function ~literate-elisp-batch-load~. \n** byte compile an org file\nTo byte compile an org file to an ~elc~ file, we can use Emacs interactive command ~literate-elisp-byte-compile-file~.\nFor example, This org file can be compiled with the following code.\n#+BEGIN_SRC elisp :load no\n(literate-elisp-byte-compile-file \"readme.org\")\n#+END_SRC\nNow the target file ~readme.org.elc~ is ready to use.\n\n** a new code block header argument ~load~\nSource blocks in a literate program can serve a variety of\npurposes—implementation, examples, testing, and so on—so we define a\n~load~ [[https://orgmode.org/manual/Structure-of-code-blocks.html][Org code block]] [[https://orgmode.org/manual/Code-block-specific-header-arguments.html#Code-block-specific-header-arguments][header argument]] to decide whether to read them\nor not, which accepts the following values -\n- yes \\\\\n  The code block should be loaded normally.\n  This is the default when the header argument ~load~ is not provided.\n  #+BEGIN_EXAMPLE\n   ,#+BEGIN_SRC elisp :load yes\n   (defun a-function-to-load ()\n    (message \"this function will be loaded by literate-elisp.~%\"))\n   ,#+END_SRC\n  #+END_EXAMPLE\n\n- no \\\\\n  The code block should be ignored by the Emacs Lisp reader.\n  #+BEGIN_EXAMPLE\n   ,#+BEGIN_SRC elisp :load no\n   (defun a-function-to-ignore ()\n    (message \"this function will be ingored by literate-elisp.~%\"))\n   ,#+END_SRC\n  #+END_EXAMPLE\n- test \\\\\n  The code block should be loaded only when the variable ~literate-elisp-test-p~ is true.\n  #+BEGIN_EXAMPLE\n   ,#+BEGIN_SRC elisp :load test\n   (defun a-function-to-test ()\n    (message \"this function will be loaded by literate-elisp only if literate-elisp-test-p is true.~%\"))\n   ,#+END_SRC\n  #+END_EXAMPLE\n- the name of a variable or function \\\\\n  The code block is loaded if the value of the variable or the return value of the function is non-nil.\n** compatibility with other libraries\nWe have some extension to keep compatibility with other libraries, the following sections show how to setup them. \n*** support for Emacs Lisp-Refs\n#+BEGIN_SRC elisp\n;; ;; To make `elisp-refs' work with `literate-elisp', we need to add an advice to `elisp-refs--read-all-buffer-forms'.\n(eval-after-load \"elisp-refs\"\n  '(advice-add 'elisp-refs--read-all-buffer-forms :around #'literate-elisp-refs--read-all-buffer-forms))\n\n;; To make `elisp-refs' work with `literate-elisp', we need to add an advice to `elisp-refs--loaded-paths'.\n(eval-after-load \"elisp-refs\"\n  '(advice-add 'elisp-refs--loaded-paths :filter-return #'literate-elisp-refs--loaded-paths))\n#+END_SRC\n*** support for library helpful\n#+BEGIN_SRC elisp\n;; To make `helpful' work with `literate-elisp', we need to add an advice to `helpful--find-by-macroexpanding'.\n(with-eval-after-load 'helpful\n  (advice-add 'helpful--find-by-macroexpanding :around #'literate-elisp-helpful--find-by-macroexpanding))\n#+END_SRC\n\n* FAQ\n** What can I do when it failed to load some file\n- try to use Emacs command =check-parens=.\n- toggle on the debug mode of literate-elisp\n#+begin_src elisp :load no\n(setf literate-elisp-debug-p t)\n#+end_src\n** Can I use =autoload= for a Elisp routine in an org file?\nYes you can, just like the original function in a elisp source file.\n\n* demo routines\n** a demo macro\nAs a demo org file, we write a simple demo macro ~aif~ here.\n\nSometimes we want to use the expression value of ~if~ condition form when it yields non-nil.\nThat's the purpose of ~aif~ which will bind variable ~it~ to the value of ~if~ condition form.\n\nWe will use some common lisp macros, so let's load this library now.\n#+BEGIN_SRC elisp\n(require 'cl)\n#+END_SRC\n\nLet's implement ~if-bind~ firstly,\nwhich can bind the value of ~if~ condition form to any specified variable.\n#+BEGIN_SRC elisp\n(defmacro if-bind (var test \u0026rest then/else)\n  \"Anaphoric IF control structure.\n\nVAR (a symbol) will be bound to the primary value of TEST. If\nTEST returns a true value then THEN will be executed, otherwise\nELSE will be executed.\"\n  (cl-assert (car then/else)\n             (then/else)\n             \"IF-BIND missing THEN clause.\")\n  (cl-destructuring-bind (then \u0026optional else)\n      then/else\n    `(lexical-let ((,var ,test))\n       (if ,var ,then ,else))))\n#+END_SRC\n\nNow ~aif~ is easy to finish.\n#+BEGIN_SRC elisp\n(defmacro aif (test then \u0026optional else)\n    \"Just like IF-BIND but the var is always IT.\"\n    `(if-bind it ,test ,then ,else))\n#+END_SRC\n\nYou can use it like this\n#+BEGIN_SRC elisp :load no\n(aif (and (y-or-n-p \"Try it\")\n            10)\n    (message \"it is %s\" it))\n#+END_SRC\nAfter loading this org file by function ~literate-elisp-load~,\nyou can use macro ~aif~ directly in your other Emacs Lisp files.\n\n* a demo Emacs configuration \nOf course the one purpose of this library is to write Emacs configuration directly in an org file. \\\\\nHere we give a demo configuration and the way to load such org config file.\n  \n** a demo configuration\n***  enable org mode for org files\n#+BEGIN_SRC elisp\n(add-to-list 'auto-mode-alist '(\"\\\\.\\\\(org\\\\|org_archive\\\\)$\" . org-mode))  \n#+END_SRC\n** load this org file in .emacs\nThen to load routines and configurations in this org file, I add the following codes in my ~.emacs~\n#+BEGIN_SRC elisp :load no\n(load \"~/projects/literate-elisp/literate-elisp.el\")\n(literate-elisp-load \"~/projects/literate-elisp/readme.org\")\n#+END_SRC\n** packages written by literate-elisp\n- [[https://github.com/jingtao-net/helm-q.el/blob/master/helm-q.org][helm-q]] Manage remote q sessions with Helm and q-mode\n* Test\n** Introduction\nWe use [[https://www.gnu.org/software/emacs/manual/html_node/ert/Introduction.html#Introduction][ERT]] library to define and run tests.\nWeb service [[https://travis-ci.com/jingtaozf/literate-lisp][travis ci]] will load config file [[./.travis.yml]] to run these tests automatically\nevery time there is a new git change.\n** test macro aif\n#+BEGIN_SRC elisp :load test\n(ert-deftest literate-demo-aif ()\n  \"A spec of macro aif.\"\n  (should (equal (aif 10 it 9) 10)))\n#+END_SRC\n** test org mode configuration\n#+BEGIN_SRC elisp :load test\n(ert-deftest literate-demo-org-mode ()\n  \"A spec of macro aif.\"\n  (should (equal (cl-loop for (x . y) in auto-mode-alist\n                          if (eq y 'org-mode)\n                          return x)\n                 \"\\\\.\\\\(org\\\\|org_archive\\\\)$\")))\n#+END_SRC\n* Copyright and license\nCode and documentation copyright 2018-2019 Jingtao Xu.\n\nThis program is free software: you can redistribute it and/or modify it \nunder the terms of the GNU General Public License as published by the Free Software Foundation,\neither version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;\nwithout even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\nSee the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program.\nIf not, see http://www.gnu.org/licenses/.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjingtaozf%2Fliterate-elisp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjingtaozf%2Fliterate-elisp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjingtaozf%2Fliterate-elisp/lists"}