{"id":15107689,"url":"https://github.com/jingtaozf/literate-smalltalk","last_synced_at":"2025-10-23T02:31:31.348Z","repository":{"id":43531677,"uuid":"324958980","full_name":"jingtaozf/literate-smalltalk","owner":"jingtaozf","description":"A literate programming tool to write Smalltalk code in org mode.","archived":false,"fork":false,"pushed_at":"2024-07-12T04:42:51.000Z","size":398,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-30T17:11:19.264Z","etag":null,"topics":["literate","literate-programming","literate-programs","pharo","pharo-smalltalk","smalltalk"],"latest_commit_sha":null,"homepage":"","language":"Smalltalk","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","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":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-28T08:45:01.000Z","updated_at":"2024-07-12T04:42:53.000Z","dependencies_parsed_at":"2023-01-27T10:45:38.861Z","dependency_job_id":null,"html_url":"https://github.com/jingtaozf/literate-smalltalk","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/jingtaozf%2Fliterate-smalltalk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingtaozf%2Fliterate-smalltalk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingtaozf%2Fliterate-smalltalk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jingtaozf%2Fliterate-smalltalk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jingtaozf","download_url":"https://codeload.github.com/jingtaozf/literate-smalltalk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237769067,"owners_count":19363250,"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":["literate","literate-programming","literate-programs","pharo","pharo-smalltalk","smalltalk"],"created_at":"2024-09-25T21:41:02.170Z","updated_at":"2025-10-23T02:31:25.750Z","avatar_url":"https://github.com/jingtaozf.png","language":"Smalltalk","funding_links":[],"categories":[],"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* Table of Contents                                                     :TOC:\n- [[#introduction][Introduction]]\n- [[#install][Install]]\n  - [[#in-pharo][in Pharo]]\n  - [[#in-emacs][in Emacs]]\n- [[#tutorial][Tutorial]]\n  - [[#preparing-an-org-file][Preparing an org file]]\n  - [[#a-quick-references-to-useful-commands][A quick references to useful commands]]\n  - [[#import-source-codes-of-some-packages][import source codes of some packages]]\n  - [[#compile-a-code-block][compile a code block]]\n  - [[#format-code-block][format code block]]\n  - [[#show-suggestions][show suggestions]]\n  - [[#delete-current-class-or-method][delete current class or method]]\n  - [[#update-source-code-block-from-pharo][update source code block from Pharo]]\n  - [[#eval-code-repl][eval code (REPL)]]\n  - [[#browse-class-or-implementors-in-pharo][browse class or implementors in Pharo]]\n  - [[#compile-all-source-code-blocks-inside-a-section][compile all source code blocks inside a section]]\n  - [[#release-current-package-to-local-file-system][release current package to local file system]]\n- [[#references][References]]\n\n* Introduction\n[[https://github.com/jingtaozf/literate-smalltalk][literate-smalltalk]] is an Emacs lisp library and a Smalltalk library to provide an easy way to use [[http://www.literateprogramming.com/][literal programming]] in Smalltalk.\n\n[[https://pharo.org/][Pharo]] is a pure object-oriented programming language and a powerful environment, focused on simplicity and immediate feedback.\nIt also provides a markdown syntax [[https://github.com/pillar-markup/MicroDown][MicroDown]] for its class comment.\n\nFrom the point of my view, Pharo is a wonderful IDE for development, except its native editor.\n\nSo here is a new literate programming environment for Pharo in Emacs org mode.\n\nIt setup a HTTP server in Pharo, so Emacs can interact with Pharo to\n- fetch packages, classes, method source\n- compile class/methods\n- format code block\n- show suggestions, etc.\n\nIn Emacs, we use an org file as both documentation and codes, and Emacs lisp library [[https://polymode.github.io/][polymode]] to enable native source code block in org mode.\nIn each code block, you can compile, format code, ask for suggestions, show compiling critiques instantly, just like it is inside Pharo.\n\nThis library contains the following files:\n- [[./literate-smalltalk.org]] \\\\\n  The implementation and documentation of both Emacs side and Pharo side.\n- [[./BaselineOfLiterateSmalltalk/BaselineOfLiterateSmalltalk.class.st][BaselineOfLiterateSmalltalk.class.st]] \\\\\n  The tangled codes of Base line for Pharo side package.\n\n- [[./LiterateSmalltalk/LiterateServer.class.st][LiterateServer.class.st]] \\\\\n  The tangled codes of Pharo side package.\n- [[./readme.org]] \\\\\n  This file contains introduction about how to do literate Smalltalk in an org file.\n\nCurrently it only tests in [[https://github.com/pharo-project/pharo][Pharo]] but other Smalltalk dialects should be easy to adopt.\n\n* Install\n** in Pharo\nYou can add this package via [[https://github.com/Metacello/metacello][metacello]] by adding a file named as =literate-server.st= in Pharo's configuration directory,\nFor Pharo 9.0 it is in =~/.config/Pharo/9.0= in Linux, or =~/Library/Preferences/pharo= in Mac OS.\nTo know the Pharo's configuration directory, please print the result of code =StartupPreferencesLoader preferencesGeneralFolder= in Pharo.\nthe file content can be like this:\n#+BEGIN_SRC smalltalk :load no\nStartupPreferencesLoader default executeAtomicItems: { (StartupAction\n\t\t\t name: 'Start Literate Server'\n\t\t\t code: [\n\t\t\t\t | class |\n\t\t\t\t class := Smalltalk at: #LiterateServer ifAbsent: [\n\t\t\t\t\t          Metacello new\n\t\t\t\t\t\t          baseline: 'LiterateSmalltalk';\n\t\t\t\t\t\t          repository: 'github://jingtaozf/literate-smalltalk';\n\t\t\t\t\t\t          onConflict: [ :ex | ex allow ];\n\t\t\t\t\t\t          load.\n\t\t\t\t\t          Smalltalk at: #LiterateServer ].\n\t\t\t\t class ifNotNil: [ LiterateServer start ] ]\n\t\t\t runOnce: false) }\n#+END_SRC\nSo each time Pharo starts, it will start a HTTP server listening in local port =9092=, which Emacs can interact with.\n\nOf course, you can also add it via [[https://github.com/pharo-vcs/iceberg][Iceberg]] manually.\n** in Emacs\nIn Emacs side, you should install Emacs library [[https://github.com/jingtaozf/literate-elisp][literate-elisp]] firstly, then load this library in Emacs like this:\n#+BEGIN_SRC elisp :load no\n(load \"~/projects/literate-elisp/literate-elisp.el\")\n(literate-elisp-load \"~/projects/literate-smalltalk/literate-smalltalk.org\")\n(add-to-list 'org-src-lang-modes '(\"smalltalk\" . \"literate-smalltalk-code\"))\n(use-package poly-org :ensure t)\n#+END_SRC\n=literate-smalltalk= provides a new major mode [[https://github.com/jingtaozf/literate-smalltalk/blob/master/literate-smalltalk.org#a-minor-mode-for-source-code][literate-smalltalk-code]] for Smalltalk source file, we also ensure [[https://polymode.github.io/][polymode]] mode\nuse it.\n\n* Tutorial\nI'll show the general workflow and features of =literate-smalltalk= in this tutorial.\n\nLet's assume that you or your team have already created a git repository and imported the codes into Pharo,\nthen you setup =literate-smalltalk= correctly so Pharo listens on port =9092= to wait for request from Emacs side.\n\n** Preparing an org file\nlet's create an org file, that's all for this step but I suggest the following lines in the beginning of an org file.\nYou can check the raw content of [[./literate-smalltalk.org]] to have a quick view.\n- enable poly-org mode\n#+begin_example\n# -*- encoding:utf-8 Mode: POLY-ORG; tab-width: 2; org-src-preserve-indentation: t; -*- ---\n#+end_example\n- remove the result part of all code block\n#+begin_example\n#+PROPERTY: header-args :results silent\n#+end_example\n- some default org properties for literate-smalltalk\n#+begin_example\n#+PROPERTY: literate-load yes\n#+PROPERTY: literate-lang smalltalk\n#+end_example\n** A quick references to useful commands\n#+BEGIN_SRC elisp :load no\n'(\n  (\"package of class\" literate-smalltalk-namespace-of-current-symbol)\n  (\"bindings of evaluation\" literate-smalltalk-eval-bindings)\n  (\"c open definition of class\" literate-smalltalk-browse-class)\n  (\"Compile codes in current header\" literate-smalltalk-execute-current-header)\n  (\"execute codes\" literate-smalltalk-execute-current-code-block)\n  (\"delete current class method\" literate-smalltalk-delete-current-class-or-method)\n  (\"format code for current code block\" literate-smalltalk-code-format-current-code-block)\n  (\"Format code for current file\" literate-smalltalk-code-format-current-file)\n  (\"i open definition of implementors\" literate-smalltalk-browse-implementors)\n  (\"run current line or selected region\" literate-smalltalk-eval-current-line-or-selected-region)\n  (\"update codes\" literate-smalltalk-update-source))\n#+END_SRC\n\n** import source codes of some packages\nGenerally speaking, the first step is importing some Smalltalk packages into our org file.\n\nWe provide two Emacs command for this purpose:\n- [[https://github.com/jingtaozf/literate-smalltalk/blob/master/literate-smalltalk.org#import-codes-of-namespaces-to-org-mode][literate-smalltalk-namespace-to-org-section]]\n\n\tIt will import the packages specified in each class's category slot.\n\tThis kind of packages are very large as it's a one level mapping between packages and classes.\n\n- [[https://github.com/jingtaozf/literate-smalltalk/blob/master/literate-smalltalk.org#import-codes-of-packages-to-org-mode][literate-smalltalk-package-to-org-section]]\n\tIt will import the packages organized by [[https://github.com/pharo-project/pharo/tree/Pharo9.0/src/RPackage-Core][RPackage]], which is the top-level packages listed in Pharo System Browser.\n\tIt is more clean way I suggest to use.\n\nNow you have some source codes inside your org file.\n** compile a code block\nA code block can contain either a class definition or a method code,\nyou can execute each source code block by Emacs command [[https://github.com/jingtaozf/literate-smalltalk/blob/master/literate-smalltalk.org#execute-source-codes-in-current-code-block][literate-smalltalk-execute-current-code-block]],\nor execute in org mode by =org-babel-execute-src-block-maybe=.\n\nAfter compiling, it will show critiques by adding them as [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Overlays.html][Overlays]].\n\nPlease note that we use the following codes for a class definition in a code block\n#+begin_src smalltalk\nObject subclass: #LiterateServer\n    instanceVariableNames: ''\n    classVariableNames: 'Server Started interactionModel transcriptLogStream'\n    package: 'LiterateSmalltalk'.\nLiterateServer class\n    instanceVariableNames: ''.\nLiterateServer comment: 'The REST Server for LiterateSmalltalk.'\n#+end_src\n** format code block\nIt is better to format code before compiling, you can do so by Emacs command [[https://github.com/jingtaozf/literate-smalltalk/blob/master/literate-smalltalk.org#command-to-code-format][literate-smalltalk-code-format-current-code-block]].\n** show suggestions\nWe use company mode to show suggestions, via Emacs command [[https://github.com/jingtaozf/literate-smalltalk/blob/master/literate-smalltalk.org#code-completion-with-company-mode][company-literate-smalltalk-code]].\nYou can press shortcut key =Alt-/= or =Tab= to show a suggestion menu.\n** delete current class or method\nYou can delete it in current code block by Emacs command [[https://github.com/jingtaozf/literate-smalltalk/blob/master/literate-smalltalk.org#command-to-delete-a-class-method][literate-smalltalk-delete-current-class-or-method]].\n** update source code block from Pharo\nSometimes you change some code inside Pharo, to get the latest code, you can update current code block by Emacs command\n[[https://github.com/jingtaozf/literate-smalltalk/blob/master/literate-smalltalk.org#update-source][literate-smalltalk-update-source]].\n** eval code (REPL)\nYou can create a code block with additional header argument =:type code=, in this case when you compile this code block,\nit is evaluated, and if you created a variable in it, you can use this variable in another code block with header argument =:type code=.\n\nFor me, I will create an individual org file for one project as an REPL for it.\n#+begin_example\n# -*- Mode: POLY-ORG; encoding: utf-8; tab-width: 2;  -*- ---\n#+Title: The REPL of literate-smalltalk\n#+OPTIONS: tex:t toc:2 \\n:nil @:t ::t |:t ^:nil -:t f:t *:t \u003c:t\n#+STARTUP: noindent\n#+STARTUP: inlineimages\n#+PROPERTY: literate-header-arguments :type code\n#+PROPERTY: literate-lang smalltalk\n#+PROPERTY: literate-load yes\n#+end_example\n\nTo just eval current line or selected region, you can run command =literate-smalltalk-eval-current-line-or-selected-region=.\n\n** browse class or implementors in Pharo\nThe Emacs command To browse class in Pharo Window is =literate-smalltalk-browse-class=.\nThe Emacs command To browse implementors in Pharo Window is =literate-smalltalk-browse-implementors=.\n** compile all source code blocks inside a section\nTo compile all source code blocks inside a section, please invoke the Emacs command [[https://github.com/jingtaozf/literate-smalltalk/blob/master/literate-smalltalk.org#execute-all-source-codes-in-current-header][literate-smalltalk-execute-current-header]].\nIt will compiling all code blocks from current point to the end of current section.\n\nIf you execute this command with command prefix =C-u=, it will execute all code blocks from current point to the end of current buffer.\n** release current package to local file system\nI [[https://github.com/jingtaozf/literate-smalltalk/blob/master/literate-smalltalk.org#release-from-pharo-to-local-file-system][release codes of this project]] to local file system by method =releaseIcebergPackage= in class =LiterateServer=.\n#+BEGIN_SRC smalltalk :type code\nLiterateServer releaseIcebergPackage: #LiterateSmalltalk.\n#+END_SRC\nI find it useful because =Iceberg= will have detached working copy sometimes.\n* References\n- [[https://github.com/dmatveev/shampoo-emacs][Shampoo mode for Emacs]]\n- [[http://www.literateprogramming.com/][Literate Programming]] a site of literate programming\n- [[https://www.youtube.com/watch?v=Av0PQDVTP4A][Literate Programming in the Large]] a talk video from Timothy Daly, one of the original authors of [[https://en.wikipedia.org/wiki/Axiom_(computer_algebra_system)][Axiom]].\n- [[https://orgmode.org/worg/org-contrib/babel/intro.html#literate-programming][literate programming in org babel]]\n- [[https://github.com/limist/literate-programming-examples][A collection of literate programming examples using Emacs Org mode]]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjingtaozf%2Fliterate-smalltalk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjingtaozf%2Fliterate-smalltalk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjingtaozf%2Fliterate-smalltalk/lists"}