readme.llar

;; Runtime configuration
;; Most of clojure and additional libraries are available

;; Fetch a source with optional processing
;;
;; (fetch SOURCE-KEY SOURCE & BODY)
;; BODY: :options, :tags, :post, :pre, :rm, :post-fns, :pre-fns, :rm-fn
;; :options - a set of options passed to the UI
;;    :mark-read-on-view - mark items as read when viewed
;;    :main-list-use-desciption - use description instead of word cloud in main list
;; :tags - a set of tags to be associated with the source
;; :post - a function to be called after filtering
;; :post-fns - a vec of functions to be called after filtering
;; :pre - a function body to be called before filtering
;; :pre-fns - a vec of functions to be called before filtering
;; :rm - a function body to be called to remove items
;; :rm-fn - a vec of functions to remove items
;;
;; All filter/pre/post functions bodies are called with special context variables:
;; Note: this does not apply to post-fns, pre-fns, rm-fn which require a function def
;; $item - the item
;; $key - the source key
;; $title - the title of the item
;; $authors - the authors of the item
;; $tags - the tags of the item
;; $raw - the raw item (not all sources support this)
;; $url - the url of the item
;; $html - the html of the item
;; $text - the text of the item
;; $options - the options of the source
;; $entry - the entry of the item
;; $score - a score if source is reddit or hackernews
;;
;; All post-fns,pre-fns, rm-fn are called with the fetched item as single argument

;; Processing functions have additional helper functions available:
;; $credentials - access credentials from credentials.edn
;; $html2text - convert html to text
;; $ellipsify - truncate text with eppipsis
;; $parse-ts - parse timestamp to zoned date time. first parameter is the format. second the string
;;             either a java time format string or a keyword from java-time.format/predefined-formatters
;;             common formatters:
;;              - :iso-date "2024-02-16"
;;		- :iso-date-time "2024-02-16T13:37:00Z"
;;		- :rfc-1123-date-time
;; $category-rm - remove items by category. usually avaiale for feed items
;; $extract - run article extraction on html content
;; $add-tag - add an item tag
;; $add-tag-filter - add a tag to items matching a filter
;; $exchange - exchange part of an item with another. usually to replace descriptions with contents
;; $html-to-hickory - convert html to hickory
;; $hickory-sanitize-blobify - run llar html sanitize and blobify on hickory
;; $make-item-hash - create item hash
;; $parse-url - parse string to URI
;; $hickory-to-html - convert hickory to html
;; $uri-path - get path from URI
;; $http-cookie-store - create HTTP cookie store for clj-http.client
;; $http-get - clj-http.client get
;; $http-post - clj-http.client post

;; And the following namespaces:
;; clojure.string as string
;; hickory.select as S
;; java-time.api as time
;; clojure.tools.logging as log

;; Example:

;; (fetch irq0 (src/feed "http://irq0.org/index.xml")
;;        :tags #{:blog})

;; Reddit sources have an additional parameter :min-score

;; (fetch-reddit (src/reddit "games" :top) :min-score 2000
;;               :options #{:mark-read-on-view}
;;               :tags #{:gaming})

;; Hacker News sources take a tag and optional filters

;; (src/hn TAG MAP-OF-FILTERS)
;; TAG is one of :front_page :comment :ask_hn :show_hn :job
;; MAP-OF-FILTERS:
;;  min-score, min-comments, created-after (timestamp), count, query (algolia query string)

;;
;; Define schedules
;;
;; Fetch feeds by using filter predicates
;;
;; (sched-fetch SCHED-NAME CHIME-TIMES PREDICATE)
;; SCHED-NAME - schedule identifier
;; CHIME-TIMES - a chime periodic seq to run fetches at
;;   either chime/periodic-seq or a keyword:
;;     :during-daytime - Daily at 10:00, 12:00, 13:00, 14:00, 16:00, 18:00
;;     :sundays - Sunday at 5:00
;;     :early-morning - Daily at 7:00
;;     :hourly - Every hour
;; PREDICATE - a filter applied to all fetchable sources
;;   context variables available:
;;     $KEY - source key as keyword (fetch SOURCE-KEY). e.g (fetch irq0) -> :irq0
;;     $SRC - source - to use with src/PREDICATES like src/mailbox?, src/reddit?, src/twitter?, src/feed?
;;     $TAGS - a set of source tags

;; Example:

;; (sched-fetch
;;   blogs
;;   :hourly
;;   (some #{:blogs} $TAGS))

;;
;; Automatically set items read after a while
;;
;; (autoread SCHED-NAME PERIOD PREDICATE)
;; SCHED-NAME - schedule identifier
;; PERIOD - a java time Period. e.g (time/weeks 2)
;; PREDICATE - a filter applied to all fetchable sources

;; Example:
;; (autoread reddit-ages-fast (time/weeks 4) (some #{:reddit} $TAGS))

;;
;; Highlight - add tag :highlight if a word, author matches
;;

;; (highlight words "llar" "rss")
;; (highlight authors "Douglas Engelbart")