From 43550de7b8db85964d95e29456ce97663c6f6f70 Mon Sep 17 00:00:00 2001 From: Bodil Stokke Date: Sat, 17 Nov 2018 22:07:08 +0000 Subject: [PATCH] Prepare for initial release. --- .travis.yml | 8 + CHANGELOG.md | 11 ++ CODE_OF_CONDUCT.md | 73 +++++++++ LICENCE.md | 355 ++++++++++++++++++++++++++++++++++++++++++ README.md | 181 +++++++++++++++++++++ macros/Cargo.toml | 7 + release.toml | 3 + typed-html/Cargo.toml | 11 ++ typed-html/src/lib.rs | 117 +++++++------- 9 files changed, 713 insertions(+), 53 deletions(-) create mode 100644 .travis.yml create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 LICENCE.md create mode 100644 README.md create mode 100644 release.toml diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..c99734a --- /dev/null +++ b/.travis.yml @@ -0,0 +1,8 @@ +language: rust +rust: + - nightly +cache: + directories: + - /home/travis/.cargo +script: + - cargo test diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..60067a9 --- /dev/null +++ b/CHANGELOG.md @@ -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. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..02a0869 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -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 diff --git a/LICENCE.md b/LICENCE.md new file mode 100644 index 0000000..cd44203 --- /dev/null +++ b/LICENCE.md @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..5df4a9b --- /dev/null +++ b/README.md @@ -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 = html!( + + + "Hello Kitty" + + + +

"Hello Kitty"

+

+ "She is not a cat. She is a human girl." +

+ { (0..3).map(|_| html!( +

+ "Her name is Kitty White." +

+ )) } +

+ "We still don't know how she eats." +

+ + +); +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 `

Hello

`, you need to + write `

"Hello"

`. (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`][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`][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`][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 = ["foo", "bar", "baz"].into(); +html!( +
+
// parses a string literal +
// uses From<[&str, &str, &str]> +
// uses a variable in scope +
+
+) +``` + +## 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!( +
    + { (1..=5).map(|i| html!( +
  • { text!("{}", i) }
    • + )) } +
+) +``` + +## 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`][DOMTree] to +ensure you're not using any event handlers that can't be printed. + +```rust +let doc: DOMTree = html!( +

"Hello Kitty"

+); +let doc_str = doc.to_string(); +assert_eq!("

Hello Kitty

", 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 +. + +## 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 diff --git a/macros/Cargo.toml b/macros/Cargo.toml index b9c4f69..7c7dc49 100644 --- a/macros/Cargo.toml +++ b/macros/Cargo.toml @@ -3,6 +3,13 @@ name = "typed-html-macros" version = "0.1.0" authors = ["Bodil Stokke "] 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] proc-macro = true diff --git a/release.toml b/release.toml new file mode 100644 index 0000000..64e554f --- /dev/null +++ b/release.toml @@ -0,0 +1,3 @@ +no-dev-version = true +sign-commit = true +pre-release-replacements = [ { file="CHANGELOG.md", search="\\[Unreleased\\]", replace="[{{version}}] - {{date}}" } ] diff --git a/typed-html/Cargo.toml b/typed-html/Cargo.toml index 088d49f..019e029 100644 --- a/typed-html/Cargo.toml +++ b/typed-html/Cargo.toml @@ -2,6 +2,17 @@ name = "typed-html" version = "0.1.0" authors = ["Bodil Stokke "] +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] typed-html-macros = { path = "../macros" } diff --git a/typed-html/src/lib.rs b/typed-html/src/lib.rs index 7fd42d3..42145fd 100644 --- a/typed-html/src/lib.rs +++ b/typed-html/src/lib.rs @@ -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! //! -//! 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. +//! 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 //! @@ -48,51 +46,51 @@ //! //! 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 `

Hello

`, you -//! need to write `

"Hello"

`. (The parser will throw an error asking you -//! to do this if you forget.) +//! * Text nodes must be quoted, because there's only so much Rust's tokeniser can +//! handle outside string literals. So, instead of `

Hello

`, you need to +//! write `

"Hello"

`. (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 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. +//! 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 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. +//! 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). +//! 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`][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`][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 +//! As a special case, if you use a string literal, the macro will instead use the +//! [`FromStr`][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`][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. +//! 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 //! @@ -120,10 +118,10 @@ //! # 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. +//! [`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 //! @@ -145,16 +143,15 @@ //! //! # Rendering //! -//! You have two options for actually producing something useful from the DOM -//! tree that comes out of the macro. +//! 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`][DOMTree] to ensure you're not using any event handlers -//! that can't be printed. +//! [`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`][DOMTree] to +//! ensure you're not using any event handlers that can't be printed. //! //! ``` //! # #![feature(proc_macro_hygiene)] @@ -171,12 +168,26 @@ //! //! ## 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. +//! 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 +//! . +//! +//! # 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