diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f7957a7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +target +gh-pages diff --git a/README.textile b/README.textile index b010a47..1f9ffed 100644 --- a/README.textile +++ b/README.textile @@ -21,6 +21,7 @@ h2. Where do I get support? "On the group":http://groups.google.com/group/enlive-clj +Here are [Generated API docs](https://cgrand.github.io/enlive/). h2. What's new in Enlive? diff --git a/doc/syntax.md b/doc/syntax.md new file mode 100644 index 0000000..7771f5d --- /dev/null +++ b/doc/syntax.md @@ -0,0 +1,152 @@ +# Selectors syntax + + + +
+
selector
+
[selector-step (:>? selector-step)*]
+
#{selector*} ; grouping
+
a-symbol ; must evaluate to a state-machine
+
(some clojure code) ; must evaluate to a state-machine
+
selector-step
+
:a-keyword ; can be :* :.class :tag :#id or any combination eg :div#foo.bar.baz
+
#{selector-step*} ; union
+
[selector-step*] ; intersection
+
a-symbol ; must evaluate to a state-machine — some are already defined
+
(some clojure code) ; must evaluate to a state-machine — better built using some predefined functions, predicate builders or macros
+
+ +

Predefined selector-steps

+root, +first-child, +last-child, +first-of-type, +last-of-type, +only-child, +only-of-type, +void (CSS's :empty), +odd and +even. + +

Predefined functions

+
+
attr? CSS
+
+
(attr? attribute-keyword*)
+

sample usage:

+
(attr? :href) ; *[href]
+(attr? :href :title) ; *[href][title]
+ +
attr= CSS
+
+
(attr= (attribute-keyword value)*)
+

sample usage:

+
(attr= :href "foo") ; *[href=foo]
+(attr= :href "foo" :title "bar") ; *[href=foo][title=bar]
+ +
attr-has CSS
+
+
(attr-has (attribute-keyword value)*)
+

sample usage:

+
(attr-has :foo "bar" "baz") ; *[foo~=bar][foo~=baz]
+ +
attr-starts CSS
+
+
(attr-starts (attribute-keyword value)*)
+

sample usage:

+
(attr-starts :href "foo" :title "bar"); *[href^=foo][title^=bar]
+ +
attr-ends CSS
+
+
(attr-ends (attribute-keyword value)*)
+

sample usage:

+
(attr-ends :href "foo" :title "bar") ; *[href$=foo][title$=bar]
+ +
attr-contains CSS
+
+
(attr-contains (attribute-keyword value)*)
+

sample usage:

+
(attr-contains :href "foo" :title "bar") ; *[href*=foo][title*=bar]
+ +
attr|= CSS
+
+
(attr|= (attribute-keyword value)*)
+

sample usage:

+
(attr|= :lang "fr") ; *[lang|=fr]
+ +
nth-child CSS
+
+
(nth-child stride? offset)
+

sample usage:

+
(nth-child 3) ; *:nth-child(3)
+(nth-child 4 2) ; *:nth-child(4n+2)
+ +
nth-last-child CSS
+
+
(nth-last-child stride? offset)
+

sample usage:

+
(nth-last-child 3) ; *:nth-last-child(3)
+(nth-last-child 4 2) ; *:nth-last-child(4n+2)
+ +
nth-of-type CSS
+
+
(nth-of-type stride? offset)
+

sample usage:

+
(nth-of-type 3) ; *:nth-of-type(3)
+(nth-of-type 4 2) ; *:nth-of-type(4n+2)
+ +
nth-last-of-type CSS
+
+
(nth-last-of-type stride? offset)
+

sample usage:

+
(nth-last-of-type 3) ; *:nth-last-of-type(3)
+(nth-last-of-type 4 2) ; *:nth-last-of-type(4n+2)
+ +
but CSS
+
+
(but selector-step)
+

sample usage:

+
(but :a) ; :not(a)
+ +
has
+
(has selector)
+

sample usage:

+
(has [:a])
+ +
+ +

Predicate builders

+These functions take a predicate and return a state-machine. +
+
pred +
+
(pred predicate-on-elements)
+

sample usage:

+
(pred #(= (:tag %) tag-name))
+ +
text-pred +
+
(text-pred predicate-on-text-nodes)
+

sample usage:

+
(text-pred #(re-matches #"\d+" %))
+ +
zip-pred +
+
(zip-pred predicate-on-elements-locs)
+ +
sm/pred (where sm aliases net.cgrand.enlive-html.state-machine) +
+
(sm/pred predicate-on-locs)
+ +
+ +

Useful macros

+selector takes a selector and evaluates to a state-machine, selector-step takes a selector-step and evaluates to a state-machine.
+They are backed by compile-selector and compile-step. diff --git a/generate_docs b/generate_docs new file mode 100755 index 0000000..bbc524e --- /dev/null +++ b/generate_docs @@ -0,0 +1,57 @@ +#!/bin/bash + +# Keep a separate branch of generated API docs. +# +# This script generates API documentation, commits it to a separate branch, and +# pushes it upstream. It does this without actually checking out the branch, +# using a separate working tree directory, so without any disruption to your +# current working tree. You can have local file modifications, but the git index +# (staging area) must be clean. + +# The git remote to fetch and push to. Also used to find the parent commit. +TARGET_REMOTE="origin" + +# Branch name to commit and push to +TARGET_BRANCH="gh-pages" + +# Command that generates the API docs +DOC_CMD="lein with-profile +codox codox" + +# Working tree directory. The output of $DOC_CMD must end up in this directory. +WORK_TREE="gh-pages" + +if ! git diff-index --quiet --cached HEAD ; then + echo "Git index isn't clean. Make sure you have no staged changes. (try 'git reset .')" + exit +fi + +git fetch $TARGET_REMOTE +rm -rf $WORK_TREE +mkdir -p $WORK_TREE + +echo "Generating docs" +$DOC_CMD + +echo "Adding file to git index" +git --work-tree=$WORK_TREE add -A + +TREE=`git write-tree` +echo "Created git tree $TREE" + +if git show-ref --quiet --verify "refs/remotes/${TARGET_REMOTE}/${TARGET_BRANCH}" ; then + PARENT=`git rev-parse ${TARGET_REMOTE}/${TARGET_BRANCH}` + echo "Creating commit with parent ${PARENT} ${TARGET_REMOTE}/${TARGET_BRANCH}" + COMMIT=`git commit-tree -p $PARENT $TREE -m 'Updating docs'` +else + echo "Creating first commit of the branch" + COMMIT=`git commit-tree $TREE -m 'Updating docs'` +fi + +echo "Commit $COMMIT" +echo "Pushing to $TARGET_BRANCH" + +git reset . +git push $TARGET_REMOTE $COMMIT:refs/heads/$TARGET_BRANCH +git fetch +echo +git log -1 --stat $TARGET_REMOTE/$TARGET_BRANCH diff --git a/project.clj b/project.clj index 78a173a..d47cb23 100644 --- a/project.clj +++ b/project.clj @@ -2,7 +2,14 @@ :min-lein-version "2.0.0" :description "a HTML selector-based (à la CSS) templating and transformation system for Clojure" :url "http://github.com/cgrand/enlive/" - :profiles {:dev {:resource-paths ["test/resources"]}} - :dependencies [[org.clojure/clojure "1.2.0"] + :profiles {:dev {:resource-paths ["test/resources"]} + :codox {:dependencies [[codox-theme-rdash "0.1.2"]] + :plugins [[lein-codox "0.10.3"]] + :codox {:project {:name "enlive"} + :metadata {:doc/format :markdown} + :themes [:rdash] + :doc-paths ["doc"] + :output-path "gh-pages"}}} + :dependencies [[org.clojure/clojure "1.6.0"] [org.ccil.cowan.tagsoup/tagsoup "1.2.1"] [org.jsoup/jsoup "1.7.2"]])