Org Ranker aims to simplify the examination of structured data within Emacs. It enables users to define top-level headlines with properties and then analyze and sort these headlines according to customized rules.
Org Ranker uses keywords to define rules. It matches headlines within an org file against these rules, and calculates a ‘score’ to assign each headline. It then sorts all headlines in the document according to their score using a relatively simple merge-sort algorithm.
- There are likely faster ways to implement this functionality, but I am relatively unexperienced with using sorting algorithms in practice, and this works for now. I have tested this with a document containing about 250 headlines, each with about 7 properties, and the entire document sorts in about 15 seconds.
Org Ranker also allows the user to define rules to exclude headlines from sorting, or rules to highlight certain headings using an overlay. Any headline which matches one of these exclusion rules is placed under a designated ‘EXCLUDE’ heading at the end of the document.
- Sort org headlines
- List headlines properties
- Highlight org headlines interactively
- Import from CSV to ORG
Basic Actions
These are the main functions that are to be the primary entry-points to this package’s functionality.
org-ranker-sortProcess all defined rules; sort, highlight, and exclude across the entire org-document. This is the main function, intended to be the primary interaction unless you want to do something more specific manually.
org-ranker-set-base-scoreSet the ‘base-score’ for a single headline. This score will not be affected by any org-ranker rules, but it will be factored in to the end score. This is useful if you want to tweak the score for a single entry without defining a rule to do so.
org-ranker-add-rule,org-ranker-add-highlight,org-ranker-add-excludeAdd a rule/highlight/exclude to the top of the file. This does not help you with rule syntax - you must still type valid information in yourself.
org-ranker-examine-propertyAllows you to specify a property or properties that you want to examine. Will open an org popup buffer listing all values for that property/properties.
org-ranker-list-propertiesLike
org-ranker-examine-property, but list all properties defined in the org-buffer.
Manual Actions (Individual)
These are manual actions that allow you to perform specific, one-off actions on a single headline. Most of these actions will be undone by other functions in this package.
org-ranker-manual-highlightHighlight a single entry with a user-defined color. Highlight will be removed on the next run of
org-ranker-highlight, ororg-ranker-sort.org-ranker-remove-highlightRemove highlighting from a single headline.
org-ranker-move-headline-(up/down)Move a single headline up/down by one headline
org-ranker-move-headline-(start/end)Move a single headline to the start/end of the buffer. Start will move the headline to the top of the buffer, after any initial content. End will move the headline to the end, or immediately before the “EXCLUDE” heading if it exists.
org-ranker-move-headline-(up/down)-nMove a single headline up/down by n headings (prompts for a number of headlines).
Manual Actions (Group)
Most of these functions are provided for convenience. The are primarily functions that are smaller components of the ‘Basic Action’ functions, allowing for more granular interaction or actions that are used infrequently.
org-ranker-excludeProcess ‘exclude’ rules.
org-ranker-unexclude“Include” headlines that are excluded, but don’t match any exclude rules.
org-ranker-highlightProcess ‘highlight’ rules.
org-ranker-remove-highlightsRemove all highlights.
org-ranker-sort-headlinesSort all headlines by their current score.
org-ranker-populate-scoresCalculate the score for all headlines based on all defined rules.
org-ranker-import-csvImport a CSV to org-mode format. Prompts for a CSV column that will become the headline. CSV data is imported to org-mode format in a temporary buffer, and all columns will become properties under the headline.
org-ranker-export-csvExport to a CSV file. Specify output file, and optionally the property names to output.
CSV Import
You can import CSV files to a temporary org-mode buffer.
Sort Headlines
Once you define some rules, you can apply them to sort your headlines and apply any highlighting/exclude rules that you have specified.
This package has not been added to Elpa or Melpa. You can install manually, or use straight.el. I don’t currently plan on changing this, primarily because I’m not sure how many people will actually find this package useful.
(straight-use-package
'(org-ranker :type git :host github :repo "CSJ7701/org-ranker"))git clone https://github.com/CSJ7701/org-ranker.elAdd the cloned files to your load path, then in your init.el file:
(require 'org-ranker)Org Ranker is designed to sort org-mode headlines based on the properties stored within them. It allows you to define rules using specific keywords (RANKER-RULE, RANKER-EXCLUDE, RANKER-HIGHLIGHT) to customize the ranking, exclusion, or highlighting of your org-mode document.
The RANKER-RULE keyword is used to assign a score to headlines based on their properties.
Each rule consists of:
- A property
- A comparator
- A value
- A score (which can be negative)
Org-Ranker will look for all headlines with that property, then match the headline’s value to the rule’s value based on the defined comparator.
If the headline matches the rule, the headline will receive the score defined in the rule.
A headline’s score is cumulative, meaning that, if it matches multiple rules, that headline’s score will be the sum of all resultant score values from each rule.
'=='- String or number matching. Requires an exact match.'~~'- Substring matching. Requires the headline’s value to contain the rule’s value.'!='- Not Equal. Matches headlines whose values are not exactly the rule’s value.'!~'- Does not contain. Matches headlines whose values do not contain the rule’s value.'>','<','>=','<='- Numerical Comparison. Note that using these to compare string values will not throw an error, but may result in unexpected matching.
# Assigns 2 points to all headlines with a 'GENDER' property of 'F'
#+RANKER-RULE: GENDER==F:2
# Assigns 10 points to all headlines with a 'LOCATION' property containing 'Florida'
#+RANKER-RULE: LOCATION~~Florida:10
# Assigns -20 points to all headlines with a 'LOCATION' property that is not 'Texas'.
#+RANKER-RULE: LOCATION!=Texas:-20
# Assigns 10 points to all headlines with an 'AGE' property greater than 30.
#+RANKER-RULE: AGE>30:10
This functionality is WIP.
The RANKER-RULE keyword can also take a function as an argument.
This function must take keyword and value as an argument, and return the score to assign the the headline.
#+RANKER-RULE: LOCATION:(my-custom-score-func)
An example of a valid function:
(defun my-custom-score-func
; WIP
)The RANKER-EXCLUDE keyword moves headlines that match the specified criteria to an ‘EXCLUDE’ heading at the end of your org document.
Each rule consists of:
- A property
- A comparator
- A value
Org-Ranker will look for all headlines with that property, then match the headline’s value to the rule’s value based on the defined comparator.
If the headline matches the rule, the headline will be moved to an ‘EXCLUDE’ heading at the end of the org document.
The same as those defined in RANKER-RULE.
#+RANKER-EXCLUDE: GENDER==M
#+RANKER-EXCLUDE: LOCATION~~Connecticut
The RANKER-HIGHLIGHT keyword highlights headings based on their properties.
Each rule consists of:
- A property
- A comparator
- A value
- A color (in hex-code format)
Org-Ranker will look for all headlines with that property, then match the headline’s value to the rule’s value based on the defined comparator.
If the headline matches the rule, the headline will be highlighted with the defined color.
The same as those defined in RANKER-RULE.
#+RANKER-HIGHLIGHT: LOCATION==12:#ff0000
#+RANKER-HIGHLIGHT: TEST==TEST VALUE:#ffd700
#+RANKER-HIGHLIGHT: LOCATION==12:#d2b48c
#+RANKER-HIGHLIGHT: ORG-RANKER-SCORE>20:#00ffff
#+RANKER-HIGHLIGHT: LOCATION!~FLORIDA:#dda0dd
#+RANKER-HIGHLIGHT: LOCATION~~FLORIDA:#000000000000
#+RANKER-HIGHLIGHT: TEST==TEST_VALUE:#ffd700
#+RANKER-RULE: GENDER==F:2
#+RANKER-RULE: LOCATION~~Florida:5
#+RANKER-RULE: LOCATION==12:-5
#+RANKER-RULE: LOCATION!=12:-5
#+RANKER-RULE: LOCATION!~Florida:10
#+RANKER-EXCLUDE: LOCATION==11
#+RANKER-HIGHLIGHT: LOCATION==12:#ff0000
#+RANKER-HIGHLIGHT: TEST==TEST VALUE:#ffd700
#+RANKER-HIGHLIGHT: LOCATION==12:#d2b48c
#+RANKER-HIGHLIGHT: ORG-RANKER-SCORE>20:#00ffff
#+RANKER-HIGHLIGHT: LOCATION!~FLORIDA:#dda0dd
#+RANKER-HIGHLIGHT: LOCATION~~FLORIDA:#000000000000
#+RANKER-HIGHLIGHT: TEST==QQQ:#ffd700
* Heading 4
:PROPERTIES:
:GENDER: F
:TEST: TEST VALUE
:ORG-RANKER-BASE-SCORE: 10
:ORG-RANKER-SCORE: 17
:END:
Some content under heading 4.
* Heading 5
:PROPERTIES:
:GENDER: F
:LOCATION: 12
:ORG-RANKER-SCORE: 7
:END:
Some content under heading 5.
* Heading 2
:PROPERTIES:
:GENDER: M
:LOCATION: 12
:ORG-RANKER-SCORE: 5
:END:
Some content under heading 2.
* Heading 3
:PROPERTIES:
:LOCATION: South Florida
:ORG-RANKER-SCORE: 0
:END:
Some content under heading 3.
* Heading 1
:PROPERTIES:
:LOCATION: FLOriDA
:ORG-RANKER-SCORE: 0
:END:
Some content under heading 1.
* EXCLUDE :exclude:
:PROPERTIES:
:ORG-RANKER-SCORE: 5
:END:
Almost all of Org Ranker’s behavior can be modified to fit your specific preference.
Take a look at the org-ranker group in Emacs’ customize interface to explore available options.
If you use the hydra package, here is an example of a hydra that could simplify the interface to this package.
(defhydra org-ranker-hydra (:color blue :hint nil)
"Org Ranker Actions: "
;; Basic Actions
("s" org-ranker-sort "Process Rules" :column "Common")
("b" org-ranker-set-base-score "Set Entry's Base Score" :column "Common")
("r" org-ranker-add-rule "Add Rule" :column "Common")
("x" org-ranker-add-exclude "Add Exclude" :column "Common")
("h" org-ranker-add-highlight "Add Highlight" :column "Common")
("p" org-ranker-examine-property "Examine Property" :column "Common")
("P" org-ranker-list-properties "List All Properties" :column "Common")
;; Manual
("mh" org-ranker-manual-highlight "Highlight Entry" :column "Manual")
("mH" org-ranker-remove-highlight "Remove Highlight on Entry" :column "Manual")
("mp" org-ranker-move-headline-up "Move Up" :column "Manual")
("mn" org-ranker-move-headline-down "Move Down" :column "Manual")
("ma" org-ranker-move-headline-start "Move to Start" :column "Manual")
("me" org-ranker-move-headline-end "Move to End" :column "Manual")
("mP" org-ranker-move-headline-up-n "Move Up N Lines" :column "Manual")
("mN" org-ranker-move-headline-down-n "Move Down N Lines" :column "Manual")
;; Manual Actions
("]" org-ranker-exclude "Process New Excludes" :column "Actions")
("[" org-ranker-unexclude "Remove Old Excludes" :column "Actions")
("{" org-ranker-highlight "Process New Highlights" :column "Actions")
("}" org-ranker-remove-highlights "Remove Old Highlights" :column "Actions")
("'" org-ranker-sort-headlines "Sort Headlines by Score" :column "Actions")
("\"" org-ranker-populate-scores "Populate Scores" :column "Actions")
;; Import
("c" org-ranker-import-csv "Import CSV File" :column "Import"))Contributions are welcome!
If there is something that does not work correctly, please open an issue.
- [ ] Update regex for ranker rule to allow for custom scoring functions
- [ ] Make ‘CSV.el’ dependency optional
- [ ] org-ranker-list-properties should work with universal argument
- [ ] Make Org-Ranker work on top level headings, and subheadings