haskal
/
skhtml
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Prepare for initial release.

This commit is contained in:
Bodil Stokke 2018-11-17 22:07:08 +00:00
parent ce0b876c50
commit 43550de7b8
9 changed files with 713 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.travis.yml Normal file
View File

@ -0,0 +1,8 @@
language: rust
rust:
- nightly
cache:
directories:
- /home/travis/.cargo
script:
- cargo test

11
CHANGELOG.md Normal file
View File

@ -0,0 +1,11 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic
Versioning](http://semver.org/spec/v2.0.0.html).
## [0.1.0] - 2018-11-17
This is the initial release.

73
CODE_OF_CONDUCT.md Normal file
View File

@ -0,0 +1,73 @@
# Contributor Covenant Code of Conduct
## Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
education, socio-economic status, nationality, personal appearance, race,
religion, or sexual identity and orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at admin@immutable.rs. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
[homepage]: https://www.contributor-covenant.org

355
LICENCE.md Normal file
View File

@ -0,0 +1,355 @@
Mozilla Public License Version 2.0
==================================
### 1. Definitions
**1.1. “Contributor”**
means each individual or legal entity that creates, contributes to
the creation of, or owns Covered Software.
**1.2. “Contributor Version”**
means the combination of the Contributions of others (if any) used
by a Contributor and that particular Contributor's Contribution.
**1.3. “Contribution”**
means Covered Software of a particular Contributor.
**1.4. “Covered Software”**
means Source Code Form to which the initial Contributor has attached
the notice in Exhibit A, the Executable Form of such Source Code
Form, and Modifications of such Source Code Form, in each case
including portions thereof.
**1.5. “Incompatible With Secondary Licenses”**
means
* **(a)** that the initial Contributor has attached the notice described
in Exhibit B to the Covered Software; or
* **(b)** that the Covered Software was made available under the terms of
version 1.1 or earlier of the License, but not also under the
terms of a Secondary License.
**1.6. “Executable Form”**
means any form of the work other than Source Code Form.
**1.7. “Larger Work”**
means a work that combines Covered Software with other material, in
a separate file or files, that is not Covered Software.
**1.8. “License”**
means this document.
**1.9. “Licensable”**
means having the right to grant, to the maximum extent possible,
whether at the time of the initial grant or subsequently, any and
all of the rights conveyed by this License.
**1.10. “Modifications”**
means any of the following:
* **(a)** any file in Source Code Form that results from an addition to,
deletion from, or modification of the contents of Covered
Software; or
* **(b)** any new file in Source Code Form that contains any Covered
Software.
**1.11. “Patent Claims” of a Contributor**
means any patent claim(s), including without limitation, method,
process, and apparatus claims, in any patent Licensable by such
Contributor that would be infringed, but for the grant of the
License, by the making, using, selling, offering for sale, having
made, import, or transfer of either its Contributions or its
Contributor Version.
**1.12. “Secondary License”**
means either the GNU General Public License, Version 2.0, the GNU
Lesser General Public License, Version 2.1, the GNU Affero General
Public License, Version 3.0, or any later versions of those
licenses.
**1.13. “Source Code Form”**
means the form of the work preferred for making modifications.
**1.14. “You” (or “Your”)**
means an individual or a legal entity exercising rights under this
License. For legal entities, “You” includes any entity that
controls, is controlled by, or is under common control with You. For
purposes of this definition, “control” means **(a)** the power, direct
or indirect, to cause the direction or management of such entity,
whether by contract or otherwise, or **(b)** ownership of more than
fifty percent (50%) of the outstanding shares or beneficial
ownership of such entity.
### 2. License Grants and Conditions
#### 2.1. Grants
Each Contributor hereby grants You a world-wide, royalty-free,
non-exclusive license:
* **(a)** under intellectual property rights (other than patent or trademark)
Licensable by such Contributor to use, reproduce, make available,
modify, display, perform, distribute, and otherwise exploit its
Contributions, either on an unmodified basis, with Modifications, or
as part of a Larger Work; and
* **(b)** under Patent Claims of such Contributor to make, use, sell, offer
for sale, have made, import, and otherwise transfer either its
Contributions or its Contributor Version.
#### 2.2. Effective Date
The licenses granted in Section 2.1 with respect to any Contribution
become effective for each Contribution on the date the Contributor first
distributes such Contribution.
#### 2.3. Limitations on Grant Scope
The licenses granted in this Section 2 are the only rights granted under
this License. No additional rights or licenses will be implied from the
distribution or licensing of Covered Software under this License.
Notwithstanding Section 2.1(b) above, no patent license is granted by a
Contributor:
* **(a)** for any code that a Contributor has removed from Covered Software;
or
* **(b)** for infringements caused by: **(i)** Your and any other third party's
modifications of Covered Software, or **(ii)** the combination of its
Contributions with other software (except as part of its Contributor
Version); or
* **(c)** under Patent Claims infringed by Covered Software in the absence of
its Contributions.
This License does not grant any rights in the trademarks, service marks,
or logos of any Contributor (except as may be necessary to comply with
the notice requirements in Section 3.4).
#### 2.4. Subsequent Licenses
No Contributor makes additional grants as a result of Your choice to
distribute the Covered Software under a subsequent version of this
License (see Section 10.2) or under the terms of a Secondary License (if
permitted under the terms of Section 3.3).
#### 2.5. Representation
Each Contributor represents that the Contributor believes its
Contributions are its original creation(s) or it has sufficient rights
to grant the rights to its Contributions conveyed by this License.
#### 2.6. Fair Use
This License is not intended to limit any rights You have under
applicable copyright doctrines of fair use, fair dealing, or other
equivalents.
#### 2.7. Conditions
Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
in Section 2.1.
### 3. Responsibilities
#### 3.1. Distribution of Source Form
All distribution of Covered Software in Source Code Form, including any
Modifications that You create or to which You contribute, must be under
the terms of this License. You must inform recipients that the Source
Code Form of the Covered Software is governed by the terms of this
License, and how they can obtain a copy of this License. You may not
attempt to alter or restrict the recipients' rights in the Source Code
Form.
#### 3.2. Distribution of Executable Form
If You distribute Covered Software in Executable Form then:
* **(a)** such Covered Software must also be made available in Source Code
Form, as described in Section 3.1, and You must inform recipients of
the Executable Form how they can obtain a copy of such Source Code
Form by reasonable means in a timely manner, at a charge no more
than the cost of distribution to the recipient; and
* **(b)** You may distribute such Executable Form under the terms of this
License, or sublicense it under different terms, provided that the
license for the Executable Form does not attempt to limit or alter
the recipients' rights in the Source Code Form under this License.
#### 3.3. Distribution of a Larger Work
You may create and distribute a Larger Work under terms of Your choice,
provided that You also comply with the requirements of this License for
the Covered Software. If the Larger Work is a combination of Covered
Software with a work governed by one or more Secondary Licenses, and the
Covered Software is not Incompatible With Secondary Licenses, this
License permits You to additionally distribute such Covered Software
under the terms of such Secondary License(s), so that the recipient of
the Larger Work may, at their option, further distribute the Covered
Software under the terms of either this License or such Secondary
License(s).
#### 3.4. Notices
You may not remove or alter the substance of any license notices
(including copyright notices, patent notices, disclaimers of warranty,
or limitations of liability) contained within the Source Code Form of
the Covered Software, except that You may alter any license notices to
the extent required to remedy known factual inaccuracies.
#### 3.5. Application of Additional Terms
You may choose to offer, and to charge a fee for, warranty, support,
indemnity or liability obligations to one or more recipients of Covered
Software. However, You may do so only on Your own behalf, and not on
behalf of any Contributor. You must make it absolutely clear that any
such warranty, support, indemnity, or liability obligation is offered by
You alone, and You hereby agree to indemnify every Contributor for any
liability incurred by such Contributor as a result of warranty, support,
indemnity or liability terms You offer. You may include additional
disclaimers of warranty and limitations of liability specific to any
jurisdiction.
### 4. Inability to Comply Due to Statute or Regulation
If it is impossible for You to comply with any of the terms of this
License with respect to some or all of the Covered Software due to
statute, judicial order, or regulation then You must: **(a)** comply with
the terms of this License to the maximum extent possible; and **(b)**
describe the limitations and the code they affect. Such description must
be placed in a text file included with all distributions of the Covered
Software under this License. Except to the extent prohibited by statute
or regulation, such description must be sufficiently detailed for a
recipient of ordinary skill to be able to understand it.
### 5. Termination
**5.1.** The rights granted under this License will terminate automatically
if You fail to comply with any of its terms. However, if You become
compliant, then the rights granted under this License from a particular
Contributor are reinstated **(a)** provisionally, unless and until such
Contributor explicitly and finally terminates Your grants, and **(b)** on an
ongoing basis, if such Contributor fails to notify You of the
non-compliance by some reasonable means prior to 60 days after You have
come back into compliance. Moreover, Your grants from a particular
Contributor are reinstated on an ongoing basis if such Contributor
notifies You of the non-compliance by some reasonable means, this is the
first time You have received notice of non-compliance with this License
from such Contributor, and You become compliant prior to 30 days after
Your receipt of the notice.
**5.2.** If You initiate litigation against any entity by asserting a patent
infringement claim (excluding declaratory judgment actions,
counter-claims, and cross-claims) alleging that a Contributor Version
directly or indirectly infringes any patent, then the rights granted to
You by any and all Contributors for the Covered Software under Section
2.1 of this License shall terminate.
**5.3.** In the event of termination under Sections 5.1 or 5.2 above, all
end user license agreements (excluding distributors and resellers) which
have been validly granted by You or Your distributors under this License
prior to termination shall survive termination.
### 6. Disclaimer of Warranty
> Covered Software is provided under this License on an “as is”
> basis, without warranty of any kind, either expressed, implied, or
> statutory, including, without limitation, warranties that the
> Covered Software is free of defects, merchantable, fit for a
> particular purpose or non-infringing. The entire risk as to the
> quality and performance of the Covered Software is with You.
> Should any Covered Software prove defective in any respect, You
> (not any Contributor) assume the cost of any necessary servicing,
> repair, or correction. This disclaimer of warranty constitutes an
> essential part of this License. No use of any Covered Software is
> authorized under this License except under this disclaimer.
### 7. Limitation of Liability
> Under no circumstances and under no legal theory, whether tort
> (including negligence), contract, or otherwise, shall any
> Contributor, or anyone who distributes Covered Software as
> permitted above, be liable to You for any direct, indirect,
> special, incidental, or consequential damages of any character
> including, without limitation, damages for lost profits, loss of
> goodwill, work stoppage, computer failure or malfunction, or any
> and all other commercial damages or losses, even if such party
> shall have been informed of the possibility of such damages. This
> limitation of liability shall not apply to liability for death or
> personal injury resulting from such party's negligence to the
> extent applicable law prohibits such limitation. Some
> jurisdictions do not allow the exclusion or limitation of
> incidental or consequential damages, so this exclusion and
> limitation may not apply to You.
### 8. Litigation
Any litigation relating to this License may be brought only in the
courts of a jurisdiction where the defendant maintains its principal
place of business and such litigation shall be governed by laws of that
jurisdiction, without reference to its conflict-of-law provisions.
Nothing in this Section shall prevent a party's ability to bring
cross-claims or counter-claims.
### 9. Miscellaneous
This License represents the complete agreement concerning the subject
matter hereof. If any provision of this License is held to be
unenforceable, such provision shall be reformed only to the extent
necessary to make it enforceable. Any law or regulation which provides
that the language of a contract shall be construed against the drafter
shall not be used to construe this License against a Contributor.
### 10. Versions of the License
#### 10.1. New Versions
Mozilla Foundation is the license steward. Except as provided in Section
10.3, no one other than the license steward has the right to modify or
publish new versions of this License. Each version will be given a
distinguishing version number.
#### 10.2. Effect of New Versions
You may distribute the Covered Software under the terms of the version
of the License under which You originally received the Covered Software,
or under the terms of any subsequent version published by the license
steward.
#### 10.3. Modified Versions
If you create software not governed by this License, and you want to
create a new license for such software, you may create and use a
modified version of this License if you rename the license and remove
any references to the name of the license steward (except to note that
such modified license differs from this License).
#### 10.4. Distributing Source Code Form that is Incompatible With Secondary Licenses
If You choose to distribute Source Code Form that is Incompatible With
Secondary Licenses under the terms of this version of the License, the
notice described in Exhibit B of this License must be attached.
## Exhibit A - Source Code Form License Notice
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
If it is not possible or desirable to put the notice in a particular
file, then You may include the notice in a location (such as a LICENSE
file in a relevant directory) where a recipient would be likely to look
for such a notice.
You may add additional accurate notices of copyright ownership.
## Exhibit B - “Incompatible With Secondary Licenses” Notice
This Source Code Form is "Incompatible With Secondary Licenses", as
defined by the Mozilla Public License, v. 2.0.

181
README.md Normal file
View File

@ -0,0 +1,181 @@
[![Build Status](https://travis-ci.org/bodil/typed-html.svg?branch=master)](https://travis-ci.org/bodil/typed-html)
# typed-html
This crate provides the `html!` macro for building HTML documents inside your
Rust code using roughly [JSX] compatible syntax.
## Nightly Warning!
This crate currently needs nightly rustc, and in order to use it you'll need to
add `#![feature(proc_macro_hygiene)]` to the top of your crate. The compiler
will tell you to do this if you forget. When this feature stabilises, the crate
should work on stable rustc without issues.
## Quick Preview
```rust
let mut doc: DOMTree<String> = html!(
<html>
<head>
<title>"Hello Kitty"</title>
<meta name=Metadata::Author content="Not Sanrio Co., Ltd"/>
</head>
<body>
<h1>"Hello Kitty"</h1>
<p class="official">
"She is not a cat. She is a human girl."
</p>
{ (0..3).map(|_| html!(
<p class="emphasis">
"Her name is Kitty White."
</p>
)) }
<p class="citation-needed">
"We still don't know how she eats."
</p>
</body>
</html>
);
let doc_str = doc.to_string();
```
## Syntax
This macro largely follows [JSX] syntax, but with some differences:
* Text nodes must be quoted, because there's only so much Rust's tokeniser can
handle outside string literals. So, instead of `<p>Hello</p>`, you need to
write `<p>"Hello"</p>`. (The parser will throw an error asking you to do this
if you forget.)
* Element attributes will accept simple Rust expressions, but the parser has
its limits, as it's not a full Rust parser. You can use literals,
variables, dotted properties, type constructors and single function or
method calls. If you use something the parser isn't currently capable of
handling, it will complain. You can put braces or parentheses around the
expression if the parser doesn't understand
it. You can use any Rust code inside a brace or parenthesis block.
## Valid HTML5
The macro will only accept valid HTML5 tags, with no tags or attributes marked
experimental or obsolete. If it won't accept something you want it to accept, we
can discuss it over a pull request (experimental tags and attributes, in
particular, are mostly omitted just for brevity, and you're welcome to implement
them).
The structure validation is simplistic by necessity, as it defers to the type
system: a few elements will have one or more required children, and any element
which accepts children will have a restriction on the type of the children,
usually a broad group as defined by the HTML spec. Many elements have
restrictions on children of children, or require a particular ordering of
optional elements, which isn't currently validated.
## Attribute Values
Brace blocks in the attribute value position should return the expected type for
the attribute. The type checker will complain if you return an unsupported type.
You can also use literals or a few simple Rust expressions as attribute values
(see the Syntax section above).
The `html!` macro will add an [`.into()`][Into::into] call to the value
expression, so that you can use any type that has an [`Into<A>`][Into] trait
defined for the actual attribute type `A`.
As a special case, if you use a string literal, the macro will instead use the
[`FromStr<A>`][FromStr] trait to try and parse the string literal into the
expected type. This is extremely useful for eg. CSS classes, letting you type
`class="css-class-1 css-class-2"` instead of going to the trouble of
constructing a [`SpacedSet<Class>`][SpacedSet]. The big caveat for this:
currently, the macro is not able to validate the string at compile time, and the
conversion will panic at runtime if the string is invalid.
### Example
```rust
let classList: SpacedSet<Class> = ["foo", "bar", "baz"].into();
html!(
<div>
<div class="foo bar baz" /> // parses a string literal
<div class=["foo", "bar", "baz"] /> // uses From<[&str, &str, &str]>
<div class=classList /> // uses a variable in scope
<div class={ // evaluates a code block
SpacedSet::from(["foo", "bar", "baz"])
} />
</div>
)
```
## Generated Nodes
Brace blocks in the child node position are expected to return an
[`IntoIterator`][IntoIterator] of [`DOMTree`][DOMTree]s. You can return single
elements or text nodes, as they both implement `IntoIterator` for themselves.
The macro will consume this iterator at runtime and insert the generated nodes
as children in the expected position.
### Example
```rust
html!(
<ul>
{ (1..=5).map(|i| html!(
<li>{ text!("{}", i) }</li>
)) }
</ul>
)
```
## Rendering
You have two options for actually producing something useful from the DOM tree
that comes out of the macro.
### Render to a string
The DOM tree data structure implements [`Display`][Display], so you can call
[`to_string()`][to_string] on it to render it to a [`String`][String]. If you
plan to do this, the type of the tree should be [`DOMTree<String>`][DOMTree] to
ensure you're not using any event handlers that can't be printed.
```rust
let doc: DOMTree<String> = html!(
<p>"Hello Kitty"</p>
);
let doc_str = doc.to_string();
assert_eq!("<p>Hello Kitty</p>", doc_str);
```
### Render to a virtual DOM
The DOM tree structure also implements a method called `vnode()`, which renders
the tree to a tree of [`Node`][Node]s, which is a mirror of the generated tree
with every attribute value rendered into `String`s. You can walk this virtual
DOM tree and use it to build an actual DOM tree with `stdweb` or pass it on to
your favourite virtual DOM system.
## Licence
Copyright 2018 Bodil Stokke
This software is subject to the terms of the Mozilla Public License, v. 2.0. If
a copy of the MPL was not distributed with this file, You can obtain one at
<http://mozilla.org/MPL/2.0/>.
## Code of Conduct
Please note that this project is released with a [Contributor Code of
Conduct][coc]. By participating in this project you agree to abide by its terms.
[coc]: https://www.contributor-covenant.org/version/1/4/code-of-conduct
[JSX]: https://reactjs.org/docs/introducing-jsx.html
[Display]: https://doc.rust-lang.org/std/fmt/trait.Display.html
[String]: https://doc.rust-lang.org/std/string/struct.String.html
[to_string]: https://doc.rust-lang.org/std/string/trait.ToString.html#tymethod.to_string
[Node]: dom/trait.Node.html
[FromStr]: https://doc.rust-lang.org/std/str/trait.FromStr.html
[SpacedSet]: types/struct.SpacedSet.html
[IntoIterator]: https://doc.rust-lang.org/std/iter/trait.IntoIterator.html
[Into]: https://doc.rust-lang.org/std/convert/trait.Into.html
[Into::into]: https://doc.rust-lang.org/std/convert/trait.Into.html#method.into
[DOMTree]: dom/type.DOMTree.html

7
macros/Cargo.toml
View File

@ -3,6 +3,13 @@ name = "typed-html-macros"
version = "0.1.0" version = "0.1.0"
authors = ["Bodil Stokke <bodil@bodil.org>"] authors = ["Bodil Stokke <bodil@bodil.org>"]
build = "build.rs" build = "build.rs"
license = "MPL-2.0+"
description = "Type checked JSX for Rust (proc_macro crate)"
repository = "https://github.com/bodil/typed-html"
documentation = "http://docs.rs/typed-html/"
readme = "../README.md"
categories = ["template-engine", "wasm", "web-programming"]
keywords = ["jsx", "html", "wasm"]
[lib] [lib]
proc-macro = true proc-macro = true

3
release.toml Normal file
View File

@ -0,0 +1,3 @@
no-dev-version = true
sign-commit = true
pre-release-replacements = [ { file="CHANGELOG.md", search="\\[Unreleased\\]", replace="[{{version}}] - {{date}}" } ]

11
typed-html/Cargo.toml
View File

@ -2,6 +2,17 @@
name = "typed-html" name = "typed-html"
version = "0.1.0" version = "0.1.0"
authors = ["Bodil Stokke <bodil@bodil.org>"] authors = ["Bodil Stokke <bodil@bodil.org>"]
license = "MPL-2.0+"
description = "Type checked JSX for Rust"
repository = "https://github.com/bodil/typed-html"
documentation = "http://docs.rs/typed-html/"
readme = "../README.md"
categories = ["template-engine", "wasm", "web-programming"]
keywords = ["jsx", "html", "wasm"]
[badges]
travis-ci = { repository = "bodil/typed-html" }
maintenance = { status = "actively-developed" }
[dependencies] [dependencies]
typed-html-macros = { path = "../macros" } typed-html-macros = { path = "../macros" }

117
typed-html/src/lib.rs
View File

@ -1,14 +1,12 @@
//! # Typed HTML //! This crate provides the `html!` macro for building HTML documents inside your
//! //! Rust code using roughly [JSX] compatible syntax.
//! This crate provides the `html!` macro for building HTML documents inside
//! your Rust code using roughly [JSX] compatible syntax.
//! //!
//! # Nightly Warning! //! # Nightly Warning!
//! //!
//! This crate currently needs nightly rustc, and in order to use it you'll need //! This crate currently needs nightly rustc, and in order to use it you'll need to
//! to add `#![feature(proc_macro_hygiene)]` to the top of your crate. The //! add `#![feature(proc_macro_hygiene)]` to the top of your crate. The compiler
//! compiler will tell you to do this if you forget. When this feature //! will tell you to do this if you forget. When this feature stabilises, the crate
//! stabilises, the crate should work on stable rustc without issues. //! should work on stable rustc without issues.
//! //!
//! # Quick Preview //! # Quick Preview
//! //!
@ -48,51 +46,51 @@
//! //!
//! This macro largely follows [JSX] syntax, but with some differences: //! This macro largely follows [JSX] syntax, but with some differences:
//! //!
//! * Text nodes must be quoted, because there's only so much Rust's tokeniser //! * Text nodes must be quoted, because there's only so much Rust's tokeniser can
//! can handle outside string literals. So, instead of `<p>Hello</p>`, you //! handle outside string literals. So, instead of `<p>Hello</p>`, you need to
//! need to write `<p>"Hello"</p>`. (The parser will throw an error asking you //! write `<p>"Hello"</p>`. (The parser will throw an error asking you to do this
//! to do this if you forget.) //! if you forget.)
//! * Element attributes will accept simple Rust expressions, but the parser has //! * Element attributes will accept simple Rust expressions, but the parser has
//! its limits, as it's not a full Rust parser. You can use literals, //! its limits, as it's not a full Rust parser. You can use literals,
//! variables, dotted properties and single function or method calls. If you //! variables, dotted properties, type constructors and single function or
//! use something the parser isn't currently capable of handling, it will //! method calls. If you use something the parser isn't currently capable of
//! complain. You can put braces or parentheses around the expression if the //! handling, it will complain. You can put braces or parentheses around the
//! parser doesn't understand it. You can use any Rust code inside a brace or //! expression if the parser doesn't understand
//! parenthesis block. //! it. You can use any Rust code inside a brace or parenthesis block.
//! //!
//! # Valid HTML5 //! # Valid HTML5
//! //!
//! The macro will only accept valid HTML5 tags, with no tags or attributes //! The macro will only accept valid HTML5 tags, with no tags or attributes marked
//! marked experimental or obsolete. If it won't accept something you want it to //! experimental or obsolete. If it won't accept something you want it to accept, we
//! accept, we can discuss it over a pull request (experimental tags and //! can discuss it over a pull request (experimental tags and attributes, in
//! attributes, in particular, are mostly omitted just for brevity, and you're //! particular, are mostly omitted just for brevity, and you're welcome to implement
//! welcome to implement them). //! them).
//! //!
//! The structure validation is simplistic by necessity, as it defers to the //! The structure validation is simplistic by necessity, as it defers to the type
//! type system: a few elements will have one or more required children, and any //! system: a few elements will have one or more required children, and any element
//! element which accepts children will have a restriction on the type of the //! which accepts children will have a restriction on the type of the children,
//! children, usually a broad group as defined by the HTML spec. Many elements //! usually a broad group as defined by the HTML spec. Many elements have
//! have restrictions on children of children, or require a particular ordering //! restrictions on children of children, or require a particular ordering of
//! of optional elements, which isn't currently validated. //! optional elements, which isn't currently validated.
//! //!
//! # Attribute Values //! # Attribute Values
//! //!
//! Brace blocks in the attribute value position should return the expected type //! Brace blocks in the attribute value position should return the expected type for
//! for the attribute. The type checker will complain if you return an //! the attribute. The type checker will complain if you return an unsupported type.
//! unsupported type. You can also use literals or a few simple Rust expressions //! You can also use literals or a few simple Rust expressions as attribute values
//! as attribute values (see the Syntax section above). //! (see the Syntax section above).
//! //!
//! The `html!` macro will add an [`.into()`][Into::into] call to the value //! The `html!` macro will add an [`.into()`][Into::into] call to the value
//! expression, so that you can use any type that has an [`Into<A>`][Into] trait //! expression, so that you can use any type that has an [`Into<A>`][Into] trait
//! defined for the actual attribute type `A`. //! defined for the actual attribute type `A`.
//! //!
//! As a special case, if you use a string literal, the macro will instead use //! As a special case, if you use a string literal, the macro will instead use the
//! the [`FromStr<A>`][FromStr] trait to try and parse the string literal into //! [`FromStr<A>`][FromStr] trait to try and parse the string literal into the
//! the expected type. This is extremely useful for eg. CSS classes, letting you //! expected type. This is extremely useful for eg. CSS classes, letting you type
//! type `class="css-class-1 css-class-2"` instead of going to the trouble of //! `class="css-class-1 css-class-2"` instead of going to the trouble of
//! constructing a [`SpacedSet<Class>`][SpacedSet]. The big caveat for this: //! constructing a [`SpacedSet<Class>`][SpacedSet]. The big caveat for this:
//! currently, the macro is not able to validate the string at compile time, and //! currently, the macro is not able to validate the string at compile time, and the
//! the conversion will panic at runtime if the string is invalid. //! conversion will panic at runtime if the string is invalid.
//! //!
//! ## Example //! ## Example
//! //!
@ -120,10 +118,10 @@
//! # Generated Nodes //! # Generated Nodes
//! //!
//! Brace blocks in the child node position are expected to return an //! Brace blocks in the child node position are expected to return an
//! [`IntoIterator`][IntoIterator] of [`DOMTree`][DOMTree]s. You can return //! [`IntoIterator`][IntoIterator] of [`DOMTree`][DOMTree]s. You can return single
//! single elements or text nodes, as they both implement `IntoIterator` for //! elements or text nodes, as they both implement `IntoIterator` for themselves.
//! themselves. The macro will consume this iterator at runtime and insert the //! The macro will consume this iterator at runtime and insert the generated nodes
//! generated nodes as children in the expected position. //! as children in the expected position.
//! //!
//! ## Example //! ## Example
//! //!
@ -145,16 +143,15 @@
//! //!
//! # Rendering //! # Rendering
//! //!
//! You have two options for actually producing something useful from the DOM //! You have two options for actually producing something useful from the DOM tree
//! tree that comes out of the macro. //! that comes out of the macro.
//! //!
//! ## Render to a string //! ## Render to a string
//! //!
//! The DOM tree data structure implements [`Display`][Display], so you can call //! The DOM tree data structure implements [`Display`][Display], so you can call
//! [`to_string()`][to_string] on it to render it to a [`String`][String]. If //! [`to_string()`][to_string] on it to render it to a [`String`][String]. If you
//! you plan to do this, the type of the tree should be //! plan to do this, the type of the tree should be [`DOMTree<String>`][DOMTree] to
//! [`DOMTree<String>`][DOMTree] to ensure you're not using any event handlers //! ensure you're not using any event handlers that can't be printed.
//! that can't be printed.
//! //!
//! ``` //! ```
//! # #![feature(proc_macro_hygiene)] //! # #![feature(proc_macro_hygiene)]
@ -171,12 +168,26 @@
//! //!
//! ## Render to a virtual DOM //! ## Render to a virtual DOM
//! //!
//! The DOM tree structure also implements a method called `vnode()`, which //! The DOM tree structure also implements a method called `vnode()`, which renders
//! renders the tree to a tree of [`Node`][Node]s, which is a mirror of the //! the tree to a tree of [`Node`][Node]s, which is a mirror of the generated tree
//! generated tree with every attribute value rendered into `String`s. You can //! with every attribute value rendered into `String`s. You can walk this virtual
//! walk this virtual DOM tree and use it to build an actual DOM tree with //! DOM tree and use it to build an actual DOM tree with `stdweb` or pass it on to
//! `stdweb` or pass it on to your favourite virtual DOM system. //! your favourite virtual DOM system.
//! //!
//! # Licence
//!
//! Copyright 2018 Bodil Stokke
//!
//! This software is subject to the terms of the Mozilla Public License, v. 2.0. If
//! a copy of the MPL was not distributed with this file, You can obtain one at
//! <http://mozilla.org/MPL/2.0/>.
//!
//! # Code of Conduct
//!
//! Please note that this project is released with a [Contributor Code of
//! Conduct][coc]. By participating in this project you agree to abide by its terms.
//!
//! [coc]: https://www.contributor-covenant.org/version/1/4/code-of-conduct
//! [JSX]: https://reactjs.org/docs/introducing-jsx.html //! [JSX]: https://reactjs.org/docs/introducing-jsx.html
//! [Display]: https://doc.rust-lang.org/std/fmt/trait.Display.html //! [Display]: https://doc.rust-lang.org/std/fmt/trait.Display.html
//! [String]: https://doc.rust-lang.org/std/string/struct.String.html //! [String]: https://doc.rust-lang.org/std/string/struct.String.html