From 4a9fa0a790aa38d9aa2881a0260f0f0870938ca0 Mon Sep 17 00:00:00 2001 From: Wouter Scherphof Date: Thu, 28 Mar 2013 12:24:10 +0100 Subject: [PATCH] First draft for a Rock setup --- .gitignore | 3 +- README.md | 77 ++++++++++++++++++- test.html => doc/sample.html | 0 test.lua => doc/sample.lua | 6 +- htmlparser-0.1-1.rockspec | 26 +++++++ htmlparser.lua => src/htmlparser.lua | 4 +- .../htmlparser/ElementNode.lua | 0 .../htmlparser/voidelements.lua | 0 8 files changed, 109 insertions(+), 7 deletions(-) rename test.html => doc/sample.html (100%) rename test.lua => doc/sample.lua (93%) create mode 100644 htmlparser-0.1-1.rockspec rename htmlparser.lua => src/htmlparser.lua (94%) rename ElementNode.lua => src/htmlparser/ElementNode.lua (100%) rename voidelements.lua => src/htmlparser/voidelements.lua (100%) diff --git a/.gitignore b/.gitignore index feff165..40e2119 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,9 @@ # LuaRocks # ###################### +bin/ lib/ share/ -bin/ +*.rock # OS generated files # ###################### diff --git a/README.md b/README.md index 2c947c2..1125a7e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,75 @@ -lua-htmlparser -============== +#LuaRock "htmlparser" -An HTML parser for lua. +Parse HTML text into a tree of elements with selectors + +###License +MIT; see ./doc/LICENSE + +###Usage +Start off with +```lua +require("luarocks.loader") +local htmlparser = require("htmlparser") +``` +Then, parse some html: +```lua +local root = htmlparser.parse(htmlstring) +``` +The input to parse may be the contents of a complete html document, or any valid html snippet, as long as all tags are correctly opened and closed. +Now, find specific elements by selecting: +```lua +local elements = root:select(selectorstring) +``` +Or in shorthand: +```lua +local elements = root(selectorstring) +``` +This wil return a Set of elements, all of which are of the same type as the root element, and thus support selecting as well, if ever needed: +```lua +for e in pairs(elements) do + print(e.name) + local subs = e(subselectorstring) + for sub in pairs(subs) do + print("", sub.name) + end +end +``` + +###Selectors +- "element" +- "#id" +- ".class" +- "[attribute]" +- "[attribute=value]" +- "[attribute!=value]" +- "[attribute|=value]" +- "[attribute*=value]" +- "[attribute~=value]" +- "[attribute^=value]" +- "[attribute$=value]" +- ":not(selector)" +- "ancestor descendant" +- "parent > child" +Selectors can be combined; e.g. ".class:not([attribute]) element.class" + +####Limitations +- Attribute values in selectors currently cannot contain any spaces, since space is interpreted as a delimiter between ancestor and descendant, parent and >, or > and child parts of the selector +- Likewise, for the parent > child relation, the spaces before and after the > are mandatory + +###Element type +The tree elements provide, apart from :select and (), the following accessors: +- .name = the elements tagname +- .attributes = a table with keys and values for the element's attributes +- .id = the value of the element's id attribute, if present +- .classes = an array with the classes listed in element's class attribute, if any +- :getcontent() = the raw text between the opening and closing tags of the element +- .nodes = an array with the element's child elements +- .parent = the elements that contains this element; root.parent is nil +- :gettext() = the raw text of the complete element, starting with `""` +- .level = how deep the element is in the tree; root level is 0 +- .root the root element of the tree; root.root is root +- .deepernodes = a Set containing all elements in the tree beneath this element, including this element's .nodes +- .deeperelements = a table with a key for each distinct tagname in .deepernodes, containing a Set of all deeper element nodes with that name +- .deeperattributes = as .deeperelements, but keyed on attribute name +- .deeperids = as .deeperelements, but keyed on id value +- .deeperclasses = as .deeperelements, but keyed on class name diff --git a/test.html b/doc/sample.html similarity index 100% rename from test.html rename to doc/sample.html diff --git a/test.lua b/doc/sample.lua similarity index 93% rename from test.lua rename to doc/sample.lua index 1eff3f6..5c85bdb 100644 --- a/test.lua +++ b/doc/sample.lua @@ -1,7 +1,10 @@ +require("luarocks.loader") +-- Omit next line in actual module clients; it's only to support development of the module itself +package.path = "../src/?.lua;" .. package.path local htmlparser = require("htmlparser") local io = require("io") -local file = io.input("./test.html") +local file = io.input("./sample.html") local text = io.read("*a") file:close() local root = htmlparser.parse(text) @@ -29,6 +32,7 @@ local function select( s ) end print(sel:len()) end + select("*") select("link") select("#/contacts/4711") diff --git a/htmlparser-0.1-1.rockspec b/htmlparser-0.1-1.rockspec new file mode 100644 index 0000000..4238859 --- /dev/null +++ b/htmlparser-0.1-1.rockspec @@ -0,0 +1,26 @@ +package = "htmlparser" +version = "0.1-1" +source = { + url = "git://github.com/wscherphof/lua-htmlparser.git", + branch = "v0.1" +} +description = { + summary = "Parse HTML text into a tree of elements with selectors", + detailed = [[ + Call parse() to build up a tree of element nodes. Each node in the tree, including the root node that is returned by parse(), supports a basic set of jQuery-like selectors. Or you could walk the tree by hand. + ]], + homepage = "http://wscherphof.github.com/lua-htmlparser/", + license = "MIT" +} +dependencies = { + "lua >= 5.2", + "set >= 0.1" +} +build = { + type = "builtin", + modules = { + htmlparser = "src/htmlparser.lua", + ["htmlparser.ElementNode"] = "src/htmlparser/ElementNode.lua", + ["htmlparser.voidelements"] = "src/htmlparser/voidelements.lua" + } +} \ No newline at end of file diff --git a/htmlparser.lua b/src/htmlparser.lua similarity index 94% rename from htmlparser.lua rename to src/htmlparser.lua index 053baad..ba6c4a6 100644 --- a/htmlparser.lua +++ b/src/htmlparser.lua @@ -1,5 +1,5 @@ -local ElementNode = require("ElementNode") -local voidelements = require("voidelements") +local ElementNode = require("htmlparser.ElementNode") +local voidelements = require("htmlparser.voidelements") local HtmlParser = {} diff --git a/ElementNode.lua b/src/htmlparser/ElementNode.lua similarity index 100% rename from ElementNode.lua rename to src/htmlparser/ElementNode.lua diff --git a/voidelements.lua b/src/htmlparser/voidelements.lua similarity index 100% rename from voidelements.lua rename to src/htmlparser/voidelements.lua