{"id":16333688,"url":"https://github.com/talyz/fromelisp","last_synced_at":"2025-03-16T14:31:12.318Z","repository":{"id":147369638,"uuid":"262605776","full_name":"talyz/fromElisp","owner":"talyz","description":"An Emacs Lisp reader in Nix.","archived":false,"fork":false,"pushed_at":"2024-08-18T13:33:17.000Z","size":98,"stargazers_count":37,"open_issues_count":2,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-16T03:05:19.339Z","etag":null,"topics":["elisp","emacs","nix","nixos"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/talyz.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"publiccode":null,"codemeta":null}},"created_at":"2020-05-09T15:54:58.000Z","updated_at":"2025-03-10T00:15:57.000Z","dependencies_parsed_at":"2024-10-27T10:55:54.706Z","dependency_job_id":"cb4b74a1-4905-484e-9772-3a5768d187ab","html_url":"https://github.com/talyz/fromElisp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/talyz%2FfromElisp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/talyz%2FfromElisp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/talyz%2FfromElisp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/talyz%2FfromElisp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/talyz","download_url":"https://codeload.github.com/talyz/fromElisp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243882451,"owners_count":20363138,"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","nix","nixos"],"created_at":"2024-10-10T23:36:17.342Z","updated_at":"2025-03-16T14:31:11.758Z","avatar_url":"https://github.com/talyz.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"#+TITLE: fromElisp\n\nAn Emacs Lisp reader in Nix. Yes, it's /necessary/.\n\n#+begin_example\n  nix-repl\u003e :p fromElisp \"(use-package lsp-mode :ensure :commands lsp)\"\n  [ [ \"use-package\" \"lsp-mode\" \":ensure\" \":commands\" \"lsp\" ] ]\n#+end_example\n\n* Functionality\n\n  ~fromElisp~ provides four main functions: ~fromElisp~, ~parseElisp~,\n  ~fromOrgModeBabelElisp~ and ~parseOrgModeBabelElisp~.\n\n  - *fromElisp* /elisp/ (string)\n\n    Takes a string argument and tries to convert the Elisp read from\n    it to the closest equivalent data type in Nix.\n\n    For example,\n    #+begin_src emacs-lisp :tangle yes\n      (use-package highlight-symbol\n        :ensure t\n        :hook (((python-mode emacs-lisp-mode nix-mode) . highlight-symbol-mode)\n               ((python-mode emacs-lisp-mode nix-mode) . highlight-symbol-nav-mode))\n        :config\n        (highlight-symbol-nav-mode)\n        (setq highlight-symbol-idle-delay 0.5)\n        (set-face-attribute 'highlight-symbol-face nil :background \"dark cyan\"))\n    #+end_src\n    is read as\n    #+begin_src nix :tangle yes\n      [[ \"use-package\" \"highlight-symbol\"\n         \":ensure\" true\n         \":hook\" [[[ \"python-mode\" \"emacs-lisp-mode\" \"nix-mode\" ] \"highlight-symbol-mode\" ]\n                  [[ \"python-mode\" \"emacs-lisp-mode\" \"nix-mode\" ] \"highlight-symbol-nav-mode\" ]]\n         \":config\"\n         [ \"highlight-symbol-nav-mode\" ]\n         [ \"setq\" \"highlight-symbol-idle-delay\" 0.5 ]\n         [ \"set-face-attribute\" [ \"quote\" \"highlight-symbol-face\" ] [ ] \":background\" \"dark cyan\" ]]]\n    #+end_src\n\n  - *parseElisp* /elisp/ (string)\n\n    Takes a string argument and provides an AST with additional\n    structural info, such as object type, line number and list depth.\n\n    The AST provided for the code\n    #+begin_src emacs-lisp :tangle yes\n      (setq mouse-wheel-scroll-amount '(3 ((shift) . 1)))\n    #+end_src\n    would be\n    #+begin_src nix :tangle yes\n      [{ depth = 0; line = 1; type = \"list\"; value = [\n           { line = 1; type = \"symbol\"; value = \"setq\"; }\n           { line = 1; type = \"symbol\"; value = \"mouse-wheel-scroll-amount\"; }\n           { line = 1; type = \"quote\"; value = {\n               depth = 1; line = 1; type = \"list\"; value = [\n                 { line = 1; type = \"integer\"; value = 3; }\n                 { depth = 2; line = 1; type = \"list\"; value = [\n                     { depth = 3; line = 1; type = \"list\"; value = [\n                         { line = 1; type = \"symbol\"; value = \"shift\"; }\n                       ];\n                     }\n                     { line = 1; type = \"integer\"; value = 1; }\n                   ];\n                 }\n               ];\n             };\n           }\n         ];\n       }]\n    #+end_src\n\n  - *fromOrgModeBabelElisp* /text/ (string)\n\n    ~fromElisp~, but for Org mode babel files. Runs ~fromElisp~ on the\n    result of tangling all Elisp code blocks with ~:tangle yes~\n    set. Tangling is done internally, not by Org mode.\n\n  - *parseOrgModeBabelElisp* /text/ (string)\n\n    ~parseElisp~, but for Org mode babel files. Runs ~parseElisp~ on the\n    result of tangling all Elisp code blocks with ~:tangle yes~\n    set. Tangling is done internally, not by Org mode.\n\n*** Other functions\n\n    - *tokenizeElisp* /elisp/ (string)\n\n      Takes a string argument and produces a list of tokens from the\n      Elisp read from it. Used internally by ~fromElisp~ and ~parseElisp~.\n\n    - *tokenizeElisp'* /args/ (attrs)\n\n      An alternate version of ~tokenizeElisp~ allowing the specification\n      of the starting line number.\n\n      /args/ is an attribute set with the following attributes:\n\n      - /elisp/ (string, required)\n\n        The string of Elisp to tokenize.\n\n      - /startLineNumber/ (int, optional)\n\n        The line number to use for the first line of /elisp/. Useful if\n        /elisp/ is a block of code from a larger file and you want line\n        numbers to be correct.\n\n    - *parseElisp'* /tokens/ (list)\n\n      An alternate version of ~parseElisp~ which takes as its argument a\n      list of tokens produced by ~tokenizeElisp~.\n\n    - *fromElisp'* /ast/ (list)\n\n      An alternate version of ~fromElisp~ which takes as its argument an\n      AST produced by ~parseElisp~.\n\n    - *tokenizeOrgModeBabelElisp* /text/ (string)\n\n      Run tokenizeElisp' on all Elisp code blocks (with ~:tangle yes~\n      set) from Org mode babel text /text/.\n\n    - *tokenizeOrgModeBabelElisp'* /defaultArgs/ (attrs) /text/ (string)\n\n      An alternate version of ~tokenizeOrgModeBabelElisp~ which allows\n      the specification of default arguments for Org babel\n      headers. Currently only ~:tangle~ is supported.\n\n    - *parseOrgBabelElisp'* /defaultArgs/ (attrs) /text/ (string)\n\n      An alternate version of ~parseOrgBabelElisp~ which allows\n      the specification of default arguments for Org babel\n      headers. Currently only ~:tangle~ is supported.\n\n    - *fromOrgBabelElisp'* /defaultArgs/ (attrs) /text/ (string)\n\n      An alternate version of ~fromOrgModeBabelElisp~ which allows\n      the specification of default arguments for Org babel\n      headers. Currently only ~:tangle~ is supported.\n\n* Usage\n\n  You can use ~fromElisp~ in your code in multiple ways.\n\n*** fetchGit\n\n    You can use ~fetchGit~ without a ~rev~ attribute to try it out quickly\n    and then add the ~rev~ when you want reproducibility.\n\n    #+begin_src nix :tangle yes\n      with (import (builtins.fetchGit {\n        url = \"https://github.com/talyz/fromElisp.git\";\n        ref = \"master\";\n        # rev = \"c13d6035666f36ca940db996f1dbaf83cb4e8453\";\n      }));\n      # ... code ...\n    #+end_src\n\n*** niv\n\n    If you use [[https://github.com/nmattia/niv][niv]] to manage your Nix dependencies, simply run\n\n    #+begin_src shell :tangle yes\n      $ niv add talyz/fromElisp\n    #+end_src\n\n    to add ~fromElisp~ to your dependencies and import it as follows:\n\n    #+begin_src nix :tangle yes\n      with (import (import ./nix/sources.nix).fromElisp {});\n      # ... code ...\n    #+end_src\n\n*** Git submodule\n\n    If you plan on contributing to ~fromElisp~ and want to do it from\n    your own source, you can import it as a [[https://git-scm.com/book/en/v2/Git-Tools-Submodules][Git submodule]].\n\n* Limitations\n\n  - No Unicode support\n\n    Nix doesn't support Unicode, so we can't either.\n\n  - No evaluation\n\n    This is a /reader/ and not an /evaluator/. You can make some pretty\n    reasonable assumptions from the structure of the code, though:\n    it's, for example, used in the [[https://github.com/nix-community/emacs-overlay][Emacs overlay]] to implement the\n    functionality of ~emacsWithPackagesFromUsePackage~.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftalyz%2Ffromelisp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftalyz%2Ffromelisp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftalyz%2Ffromelisp/lists"}