diff --git a/.gitignore b/.gitignore index 64b1053..455bc57 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ /.cask/ +/test.md diff --git a/.travis.yml b/.travis.yml index 30acddc..3a67b95 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,4 +1,5 @@ language: emacs-lisp +sudo: false env: global: - PATH=$HOME/.cask/bin:$HOME/.evm/bin:$PATH @@ -10,9 +11,8 @@ env: - EVM_EMACS=emacs-24.5-bin before_install: # evm install - - curl -fsSkL https://gist.github.com/rejeep/7736123/raw > travis.sh && source ./travis.sh + - curl -fsSkL https://gist.github.com/rejeep/ebcd57c3af83b049833b/raw > x.sh && source ./x.sh # install the matrix's emacs version - - evm install $EVM_EMACS --use --skip - cask --version - emacs --version # install deps for cask diff --git a/README.md b/README.md index 5599a36..63af408 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,11 @@ markdown-toc -A simple mode to create TOC in a markdown file. +A simple mode to create TOC in a well-formed markdown file. + +Limitations: + +The TOC is well-formed if the markdown is. (cf. #15) # Use @@ -55,15 +59,63 @@ Here is one possible output: - [Inspiration](#inspiration) ``` +## User toc manipulation + +If the user would want to enhance the generated toc, (s)he could use +the following function markdown-toc-user-toc-structure-manipulation-fn: + +It expects as argument the toc-structure markdown-toc uses to generate +the toc. The remaining code expects a similar structure. + +Example: + +``` lisp +'((0 . \"some markdown page title\") + (0 . \"main title\") + (1 . \"Sources\") + (2 . \"Marmalade (recommended)\") + (2 . \"Melpa-stable\") + (2 . \"Melpa (~snapshot)\") + (1 . \"Install\") + (2 . \"Load org-trello\") + (2 . \"Alternative\") + (3 . \"Git\") + (3 . \"Tar\") + (0 . \"another title\") + (1 . \"with\") + (1 . \"some\") + (1 . \"heading\")) +``` + +So for example, as asked in #16, one could drop the first element: + +``` lisp +(custom-set-variables '(markdown-toc-user-toc-structure-manipulation-fn 'cdr)) +``` + +Or drop all h1 titles... or whatever: + +``` lisp +(require 'dash) +(custom-set-variables '(markdown-toc-user-toc-structure-manipulation-fn + (lambda (toc-structure) + (-filter (lambda (l) (let ((index (car l))) + (<= 1 index))) + toc-structure))) +``` + ## Update -To update the existing TOC, simply execute again: C-u M-x markdown-toc-generate-toc +To update the existing TOC, simply execute again: +C-u M-x markdown-toc-generate-toc This will update the current TOC. ## Create elsewhere -To create another updated TOC elsewhere, execute again M-x markdown-toc-generate-toc, this will remove the old TOC and insert the updated one from where you stand. +To create another updated TOC elsewhere, execute again M-x +markdown-toc-generate-toc, this will remove the old TOC and +insert the updated one from where you stand. # Install @@ -77,7 +129,8 @@ You need to add melpa or melpa-stable package repository before installing it. ``` lisp (require 'package) -(add-to-list 'package-archives '("melpa-stable" . "https://stable.melpa.org/packages/")) +(add-to-list 'package-archives '("melpa-stable" . + "http://melpa-stable.milkbox.net/packages/")) (package-initialize) ``` @@ -87,7 +140,8 @@ Then hit M-x eval-buffer to evaluate the buffer's contents. ``` lisp (require 'package) -(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/")) +(add-to-list 'package-archives '("melpa" . + "http://melpa.milkbox.net/packages/")) (package-initialize) ``` @@ -97,7 +151,8 @@ Then hit M-x eval-buffer to evaluate the buffer's contents. ``` lisp (require 'package) -(add-to-list 'package-archives '("marmalade" . "http://marmalade-repo.org/packages/")) +(add-to-list 'package-archives '("marmalade" . + "http://marmalade-repo.org/packages/")) (package-initialize) ``` diff --git a/markdown-toc-pkg.el b/markdown-toc-pkg.el index d2a1ea7..0a70696 100644 --- a/markdown-toc-pkg.el +++ b/markdown-toc-pkg.el @@ -1,4 +1,4 @@ -(define-package "markdown-toc" "0.0.8" "A simple TOC generator for markdown file" +(define-package "markdown-toc" "0.0.9" "A simple TOC generator for markdown file" '((s "1.9.0") (dash "2.11.0") (markdown-mode "2.0"))) diff --git a/markdown-toc.el b/markdown-toc.el index 7b588a5..6e1e1f6 100644 --- a/markdown-toc.el +++ b/markdown-toc.el @@ -5,7 +5,7 @@ ;; Maintainer: Antoine R. Dumont ;; URL: http://github.com/ardumont/markdown-toc ;; Created: 24th May 2014 -;; Version: 0.0.8 +;; Version: 0.0.9 ;; Keywords: markdown, toc, tools, ;; Package-Requires: ((markdown-mode "2.0") (dash "2.11.0") (s "1.9.0")) @@ -62,7 +62,7 @@ (require 'dash) (require 'markdown-mode) -(defconst markdown--toc-version "0.0.8" "Current version installed.") +(defconst markdown--toc-version "0.0.9" "Current version installed.") ;;;###autoload (defun markdown-toc-version () @@ -79,7 +79,9 @@ (tail (cdr menu-index)) (ttail (if (integerp tail) nil (cdr tail)))) (cons `(,level . ,fst) - (--mapcat (markdown-toc--compute-toc-structure-from-level (+ 1 level) it) ttail))))) + (--mapcat + (markdown-toc--compute-toc-structure-from-level (+ 1 level) it) + ttail))))) (defun markdown-toc--compute-toc-structure (imenu-index) "Given a IMENU-INDEX, compute the TOC structure." @@ -88,29 +90,32 @@ (defun markdown-toc--symbol (sym n) "Compute the repetition of a symbol SYM N times as a string." (--> n - (-repeat it sym) - (s-join "" it))) + (-repeat it sym) + (s-join "" it))) (defun markdown-toc--to-link (title) "Given a TITLE, return the markdown link associated." (format "[%s](#%s)" title - (->> - title - downcase - (replace-regexp-in-string "[^a-z0-9 -]" "") - (s-replace " " "-")))) + (->> title + downcase + (replace-regexp-in-string "[^a-z0-9 -]" "") + (s-replace " " "-")))) (defun markdown-toc--to-markdown-toc (level-title-toc-list) "Given LEVEL-TITLE-TOC-LIST, a list of pair level, title, return a TOC string." (->> level-title-toc-list - (--map (let ((nb-spaces (* 4 (car it))) - (title (cdr it))) - (format "%s- %s" (markdown-toc--symbol " " nb-spaces) (markdown-toc--to-link title)))) - (s-join "\n"))) - -(defconst markdown-toc--header-toc-start "") -(defconst markdown-toc--header-toc-title "**Table of Contents**") -(defconst markdown-toc--header-toc-end "") + (--map (let ((nb-spaces (* 4 (car it))) + (title (cdr it))) + (format "%s- %s" (markdown-toc--symbol " " nb-spaces) + (markdown-toc--to-link title)))) + (s-join "\n"))) + +(defconst markdown-toc--header-toc-start + "") +(defconst markdown-toc--header-toc-title + "**Table of Contents**") +(defconst markdown-toc--header-toc-end + "") (defun markdown-toc--toc-already-present-p () "Determine if a TOC has already been generated. @@ -131,10 +136,9 @@ Return the end position if it exists, nil otherwise." (goto-char (point-min)) (re-search-forward markdown-toc--header-toc-end nil t))) -(defun markdown-toc--generate-toc (toc-index) - "Given a TOC-INDEX, compute a new toc." - (-> toc-index - markdown-toc--compute-toc-structure +(defun markdown-toc--generate-toc (toc-structure) + "Given a TOC-STRUCTURE, compute a new toc." + (-> toc-structure markdown-toc--to-markdown-toc markdown-toc--compute-full-toc)) @@ -146,7 +150,36 @@ Return the end position if it exists, nil otherwise." toc markdown-toc--header-toc-end)) +(defcustom markdown-toc-user-toc-structure-manipulation-fn + (lambda (toc-structure) toc-structure) + "User crafted function to manipulate toc-structure as user sees fit. + +The toc-structure has the following form: +'((0 . \"some markdown page title\") + (0 . \"main title\") + (1 . \"Sources\") + (2 . \"Marmalade (recommended)\") + (2 . \"Melpa-stable\") + (2 . \"Melpa (~snapshot)\") + (1 . \"Install\") + (2 . \"Load org-trello\") + (2 . \"Alternative\") + (3 . \"Git\") + (3 . \"Tar\") + (0 . \"another title\") + (1 . \"with\") + (1 . \"some\") + (1 . \"heading\")) + +If the user wanted to remove the first element, it could for +example define the following function: + (custom-set-variables + '(markdown-toc-user-toc-structure-manipulation-fn 'cdr)) + +Default to identity function (do nothing).") + ;;;###autoload + (defun markdown-toc-generate-toc (&optional replace-toc-p) "Generate a TOC for markdown file at current point. Deletes any previous TOC. @@ -158,12 +191,13 @@ If called interactively with prefix arg REPLACE-TOC-P, replaces previous TOC." (let ((region-start (markdown-toc--toc-start)) (region-end (markdown-toc--toc-end))) (delete-region region-start (1+ region-end)) - (if replace-toc-p - (goto-char region-start)))) - ;; generate the toc - (-> (markdown-imenu-create-index) - markdown-toc--generate-toc - insert))) + (when replace-toc-p + (goto-char region-start)))) + (->> (markdown-imenu-create-index) + markdown-toc--compute-toc-structure + (funcall markdown-toc-user-toc-structure-manipulation-fn) + markdown-toc--generate-toc + insert))) (defalias 'markdown-toc/generate-toc 'markdown-toc-generate-toc) diff --git a/release-notes.md b/release-notes.md index 22e7995..9074743 100644 --- a/release-notes.md +++ b/release-notes.md @@ -1,3 +1,11 @@ +# 0.0.9 + +- [X] Permit user-custom function to manipulate toc some more - #16 +- [X] Improve testing +- [X] Clean some code +- [X] Update version +- [X] Clean up tests + # 0.0.8 - [X] Add test coverage diff --git a/test/load-markdown-toc-tests.el b/test/load-markdown-toc-tests.el deleted file mode 100644 index b86691c..0000000 --- a/test/load-markdown-toc-tests.el +++ /dev/null @@ -1,27 +0,0 @@ -;;; load-markdown-toc-tests.el --- Load the namespaces for tests -;;; Commentary: -;;; Code: - -(message "Launching tests!") - -;; load code prod -(load-file "./markdown-toc.el") - -;; Add test folder to the load path -(add-to-list 'load-path (expand-file-name "./test")) - -(message "Loading tests done!") - -(require 'markdown-toc) - -(defun markdown-toc/test-load-namespaces! () - "Load the org-trello namespaces." - (interactive) - (mapc #'load-file '("./test/markdown-toc-tests.el"))) - -(markdown-toc/test-load-namespaces!) - -(require 'markdown-toc-tests) - -(provide 'load-markdown-toc-tests) -;;; load-markdown-toc-tests.el ends here diff --git a/test/markdown-toc-test.el b/test/markdown-toc-test.el old mode 100644 new mode 100755 index ab9a207..bb8b486 --- a/test/markdown-toc-test.el +++ b/test/markdown-toc-test.el @@ -1,5 +1,6 @@ (require 'ert) (require 'el-mock) +(require 'markdown-toc) (ert-deftest markdown-toc--symbol () (should (equal " " (markdown-toc--symbol " " 3))) @@ -91,15 +92,29 @@ "\n**Table of Contents**\n\nsome-toc\n\n\n" (markdown-toc--compute-full-toc "some-toc")))) +(defmacro markdown-toc-with-temp-buffer-and-return-buffer-content (text body-test) + "A `markdown-toc' test macro to ease testing. +TEXT is the content of the buffer. +BODY-TEST is the assertion to test on the buffer. +NB-LINES-FORWARD is the number of lines to get back to." + `(with-temp-buffer + (markdown-mode) + (insert ,text) + (progn + (goto-char (point-min)) + ,body-test + (buffer-substring-no-properties (point-min) (point-max))))) + ;; Create a new TOC (ert-deftest markdown-toc-generate-toc--first-toc () (should (equal " **Table of Contents** -- [-](#-) - - [Marmalade (recommended)](#marmalade-recommended) - - [Melpa-stable](#melpa-stable) - - [Melpa (~snapshot)](#melpa-snapshot) +- [something](#something) + - [Sources](#sources) + - [Marmalade (recommended)](#marmalade-recommended) + - [Melpa-stable](#melpa-stable) + - [Melpa (~snapshot)](#melpa-snapshot) - [Install](#install) - [Load org-trello](#load-org-trello) - [Alternative](#alternative) @@ -108,6 +123,7 @@ To install **org-trello** in your emacs, you need a few steps. +# something ## Sources If not already configured, you need to prepare emacs to work with marmalade or melpa. For this, you need to install a snippet of code in your emacs configuration file. @@ -120,10 +136,9 @@ For this, you need to install a snippet of code in your emacs configuration file #### Git #### Tar " - (with-temp-buffer - (markdown-mode) - (require 'markdown-toc) - (insert "To install **org-trello** in your emacs, you need a few steps. + (markdown-toc-with-temp-buffer-and-return-buffer-content + "To install **org-trello** in your emacs, you need a few steps. +# something ## Sources If not already configured, you need to prepare emacs to work with marmalade or melpa. For this, you need to install a snippet of code in your emacs configuration file. @@ -135,19 +150,65 @@ For this, you need to install a snippet of code in your emacs configuration file ### Alternative #### Git #### Tar -") - (goto-char (point-min)) - (markdown-toc-generate-toc) - (buffer-substring-no-properties (point-min) (point-max)))))) +" + (markdown-toc-generate-toc))))) -(ert-deftest markdown-toc-generate-toc--replace-old-toc () +(ert-deftest markdown-toc-generate-toc--first-toc-with-user-override () (should (equal " **Table of Contents** -- [-](#-) - - [Marmalade (recommended)](#marmalade-recommended) - - [Melpa-stable](#melpa-stable) - - [Melpa (~snapshot)](#melpa-snapshot) + - [Sources](#sources) + - [Marmalade (recommended)](#marmalade-recommended) + - [Melpa-stable](#melpa-stable) + - [Melpa (~snapshot)](#melpa-snapshot) + - [Install](#install) + - [Load org-trello](#load-org-trello) + - [Alternative](#alternative) + - [Git](#git) + - [Tar](#tar) + + +To install **org-trello** in your emacs, you need a few steps. +# something +## Sources +If not already configured, you need to prepare emacs to work with marmalade or melpa. +For this, you need to install a snippet of code in your emacs configuration file. +### Marmalade (recommended) +### Melpa-stable +### Melpa (~snapshot) +## Install +### Load org-trello +### Alternative +#### Git +#### Tar +" + (let ((markdown-toc-user-toc-structure-manipulation-fn 'cdr)) + (markdown-toc-with-temp-buffer-and-return-buffer-content + "To install **org-trello** in your emacs, you need a few steps. +# something +## Sources +If not already configured, you need to prepare emacs to work with marmalade or melpa. +For this, you need to install a snippet of code in your emacs configuration file. +### Marmalade (recommended) +### Melpa-stable +### Melpa (~snapshot) +## Install +### Load org-trello +### Alternative +#### Git +#### Tar +" + (markdown-toc-generate-toc)))))) + +(ert-deftest markdown-toc-generate-toc--replace-old-toc-if-already-present () + (should (equal " +**Table of Contents** + +- [Packages](#packages) + - [Sources](#sources) + - [Marmalade (recommended)](#marmalade-recommended) + - [Melpa-stable](#melpa-stable) + - [Melpa (~snapshot)](#melpa-snapshot) - [Install](#install) - [Load org-trello](#load-org-trello) - [Alternative](#alternative) @@ -156,6 +217,7 @@ For this, you need to install a snippet of code in your emacs configuration file To install **org-trello** in your emacs, you need a few steps. +# Packages ## Sources If not already configured, you need to prepare emacs to work with marmalade or melpa. For this, you need to install a snippet of code in your emacs configuration file. @@ -168,13 +230,10 @@ For this, you need to install a snippet of code in your emacs configuration file #### Git #### Tar " - (with-temp-buffer - (markdown-mode) - (require 'markdown-toc) - (insert " + (markdown-toc-with-temp-buffer-and-return-buffer-content + " **Table of Contents** -- [-](#-) - [Melpa (~snapshot)](#melpa-snapshot) - [Install](#install) - [Load org-trello](#load-org-trello) @@ -184,6 +243,7 @@ For this, you need to install a snippet of code in your emacs configuration file To install **org-trello** in your emacs, you need a few steps. +# Packages ## Sources If not already configured, you need to prepare emacs to work with marmalade or melpa. For this, you need to install a snippet of code in your emacs configuration file. @@ -195,10 +255,8 @@ For this, you need to install a snippet of code in your emacs configuration file ### Alternative #### Git #### Tar -") - (goto-char (point-min)) - (markdown-toc-generate-toc) - (buffer-substring-no-properties (point-min) (point-max)))))) +" + (markdown-toc-generate-toc))))) (ert-deftest markdown-toc-generate-toc--replace-old-toc () ;; Update an existing TOC @@ -207,10 +265,11 @@ For this, you need to install a snippet of code in your emacs configuration file **Table of Contents** -- [-](#-) - - [Marmalade (recommended)](#marmalade-recommended) - - [Melpa-stable](#melpa-stable) - - [Melpa (~snapshot)](#melpa-snapshot) +- [Packages](#packages) + - [Sources](#sources) + - [Marmalade (recommended)](#marmalade-recommended) + - [Melpa-stable](#melpa-stable) + - [Melpa (~snapshot)](#melpa-snapshot) - [Install](#install) - [Load org-trello](#load-org-trello) - [Alternative](#alternative) @@ -219,6 +278,7 @@ For this, you need to install a snippet of code in your emacs configuration file To install **org-trello** in your emacs, you need a few steps. +# Packages ## Sources If not already configured, you need to prepare emacs to work with marmalade or melpa. For this, you need to install a snippet of code in your emacs configuration file. @@ -231,15 +291,12 @@ For this, you need to install a snippet of code in your emacs configuration file #### Git #### Tar " - (with-temp-buffer - (markdown-mode) - (require 'markdown-toc) - (insert "some foo bar before + (markdown-toc-with-temp-buffer-and-return-buffer-content + "some foo bar before **Table of Contents** -- [-](#-) - [Melpa (~snapshot)](#melpa-snapshot) - [Install](#install) - [Load org-trello](#load-org-trello) @@ -249,6 +306,7 @@ For this, you need to install a snippet of code in your emacs configuration file To install **org-trello** in your emacs, you need a few steps. +# Packages ## Sources If not already configured, you need to prepare emacs to work with marmalade or melpa. For this, you need to install a snippet of code in your emacs configuration file. @@ -260,10 +318,8 @@ For this, you need to install a snippet of code in your emacs configuration file ### Alternative #### Git #### Tar -") - (goto-char (point-min)) - (markdown-toc-generate-toc 'replace-old-toc) - (buffer-substring-no-properties (point-min) (point-max)))))) +" + (markdown-toc-generate-toc 'replace-old-toc))))) (provide 'markdown-toc-tests) ;;; markdown-toc-tests.el ends here diff --git a/todo.org b/todo.org index 8c53030..a5f8cdd 100644 --- a/todo.org +++ b/todo.org @@ -1,6 +1,14 @@ #+title: dev backlog #+author: ardumont +* DONE 0.0.9 [100%] +CLOSED: [2015-12-23 Wed 11:59] +- [X] Permit user-custom function to manipulate toc some more - #16 +- [X] Improve testing +- [X] Clean some code +- [X] Update version +- [X] Clean up tests +- [X] Release notes * DONE 0.0.8 [100%] CLOSED: [2015-07-15 Wed 17:12] - [X] Add test coverage