├── .gitignore ├── CONTRIBUTING.md ├── LICENSE-APACHE ├── LICENSE-MIT ├── README.md ├── book.json ├── dictionary.txt ├── examples └── lorem.txt ├── justfile ├── spellcheck.sh ├── src ├── SUMMARY.md ├── appendix-00-contributors.md ├── appendix-01-contributing.md ├── ch00-00-introduction.md ├── ch00-01-before-we-begin.md ├── ch00-02-about.md ├── ch00-03-terms.md ├── ch01-00-command-line-applications.md ├── ch01-01-00-interface.md ├── ch01-01-01-controller.md ├── ch01-01-02-config.md ├── ch01-01-03-00-results.md ├── ch01-01-03-01-errors.md ├── ch01-01-03-output.md ├── ch01-01-04-application.md ├── ch01-01-components.md ├── ch01-02-rwc.md └── img │ └── ch01-00-components.png └── style-guide.md /.gitignore: -------------------------------------------------------------------------------- 1 | .conifg/ 2 | book 3 | .*~ 4 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | We would love issues and pull requests to the Markdown files in the src directory. The chapters we 4 | have planned but that we have not yet written appear greyed out in the sidebar of the rendered book. 5 | We would love issues with ideas for what, specifically, you'd like to see covered in those planned 6 | chapters! 7 | 8 | Our [open pull requests][pulls] are new chapters or edits that we're currently 9 | working on. We would love if you would read through those and make comments for 10 | any suggestions or corrections! 11 | 12 | [pulls]: https://github.com/kbknapp/clap-book/pulls 13 | 14 | If you're looking for ways to help that don't involve reading or writing, check 15 | out the [open issues with the M-help-wanted label][help-wanted]. These might be 16 | Rust code, frontend code, or shell scripts that would help us be more efficient 17 | or enhance the book in some way! 18 | 19 | [help-wanted]: https://github.com/kbknapp/clap-book/issues?q=is%3Aopen+is%3Aissue+label%3AM-help-wanted 20 | 21 | This repository is under the same license as Rust itself, MIT/Apache2. 22 | -------------------------------------------------------------------------------- /LICENSE-APACHE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /LICENSE-MIT: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015-2016 Kevin B. Knapp 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The Rust Programming Language 2 | 3 | [![Build Status](https://travis-ci.org/kbknapp/clap-book.svg?branch=master)](https://travis-ci.org/kbknapp/clap-book) 4 | 5 | This is the book “Building Command Line Utilities in Rust”, which is currently rendered 6 | [online][prod]. 7 | 8 | [prod]: https://book.clap.rs/ 9 | 10 | ## Requirements 11 | 12 | Building the book requires [mdBook] >= v0.0.13. To get it: 13 | 14 | [mdBook]: https://github.com/azerupi/mdBook 15 | 16 | ``` 17 | $ cargo install mdbook 18 | ``` 19 | 20 | ## Building 21 | 22 | To build the book, type: 23 | 24 | ``` 25 | $ mdbook build 26 | ``` 27 | 28 | The output will be in the `book` subdirectory. To check it out, open it in 29 | your web browser. 30 | 31 | _Firefox:_ 32 | ``` 33 | $ firefox book/index.html # Linux 34 | $ open -a "Firefox" book/index.html # OS X 35 | ``` 36 | 37 | _Chrome:_ 38 | ``` 39 | $ google-chrome book/index.html # Linux 40 | $ open -a "Google Chrome" book/index.html # OS X 41 | ``` 42 | 43 | To run the tests: 44 | 45 | ``` 46 | $ mdbook test 47 | ``` 48 | 49 | ## Contributing 50 | 51 | We'd love your help! Please see [CONTRIBUTING.md][contrib]. 52 | 53 | [contrib]: https://github.com/kbknapp/clap-book/blob/master/CONTRIBUTING.md 54 | 55 | ## Spellchecking 56 | 57 | To scan source files for spelling errors, you can use the `spellcheck.sh` 58 | script. It needs a dictionary of valid words, which is provided in 59 | `dictionary.txt`. If the script produces a false positive (say, you used word 60 | `BTreeMap` which the script considers invalid), you need to add this word to 61 | `dictionary.txt` (keep the sorted order for consistency). 62 | 63 | ## Converting Windows newlines to Unix 64 | 65 | This is mostly for Carol's reference because she keeps having to look it up. 66 | 67 | ``` 68 | $ tr -d '\015' < DOS-file > UNIX-file 69 | ``` 70 | -------------------------------------------------------------------------------- /book.json: -------------------------------------------------------------------------------- 1 | { 2 | "title": "Building Command Line Utilities in Rust", 3 | "author": "Kevin Knapp" 4 | } -------------------------------------------------------------------------------- /dictionary.txt: -------------------------------------------------------------------------------- 1 | personal_ws-1.1 en 0 utf-8 2 | abcabcabc 3 | abcd 4 | Addr 5 | aliasability 6 | alignof 7 | Amir 8 | APIs 9 | aren 10 | args 11 | backtrace 12 | backtraces 13 | BACKTRACE 14 | Backtraces 15 | benchmarking 16 | bitand 17 | BitAnd 18 | bitor 19 | BitOr 20 | bitwise 21 | Bitwise 22 | bitxor 23 | BitXor 24 | Boehm 25 | bool 26 | boolean 27 | booleans 28 | Bors 29 | BuildHasher 30 | Cagain 31 | callsite 32 | CamelCase 33 | ChangeColor 34 | ChangeColorMessage 35 | chXX 36 | chYY 37 | config 38 | Config 39 | const 40 | constant's 41 | copyeditor 42 | couldn 43 | cratesio 44 | cryptographically 45 | CStr 46 | CString 47 | ctrl 48 | Ctrl 49 | deallocated 50 | deallocating 51 | debuginfo 52 | deps 53 | deref 54 | Deref 55 | dereference 56 | Dereference 57 | dereferencing 58 | DerefMut 59 | destructure 60 | destructuring 61 | Destructuring 62 | didn 63 | Dobrý 64 | doccargo 65 | doccratesio 66 | doesn 67 | Edsger 68 | else's 69 | emoji 70 | encodings 71 | enum 72 | Enum 73 | enums 74 | enum's 75 | Enums 76 | ErrorKind 77 | Executables 78 | extern 79 | FFFF 80 | figcaption 81 | filename 82 | Filename 83 | filesystem 84 | Filesystem 85 | formatter 86 | GitHub 87 | gitignore 88 | grapheme 89 | Grapheme 90 | greprs 91 | growable 92 | hardcoded 93 | hardcoding 94 | hasher 95 | hashmap 96 | HashMap 97 | Hashmaps 98 | Haskell 99 | hasn 100 | helloworld 101 | Hmmm 102 | Hoare 103 | Hola 104 | homogenous 105 | html 106 | IEEE 107 | impl 108 | indices 109 | init 110 | instantiation 111 | internet 112 | InvalidDigit 113 | ioerror 114 | iokind 115 | ioresult 116 | iostdin 117 | IpAddr 118 | IpAddrKind 119 | irst 120 | isize 121 | iter 122 | JavaScript 123 | lang 124 | latin 125 | libc 126 | libcore 127 | librarys 128 | libreoffice 129 | lifecycle 130 | loopback 131 | lval 132 | mathematic 133 | Metadata 134 | metaprogramming 135 | mibbit 136 | Mibbit 137 | mkdir 138 | modifiability 139 | monomorphization 140 | Monomorphization 141 | monomorphized 142 | MoveMessage 143 | Mutex 144 | namespace 145 | namespaced 146 | namespaces 147 | namespacing 148 | newfound 149 | newtype 150 | nocapture 151 | nomicon 152 | Nomicon 153 | NotFound 154 | null's 155 | OCaml 156 | offsetof 157 | online 158 | OptionalFloatingPointNumber 159 | OptionalNumber 160 | OsStr 161 | OsString 162 | overread 163 | parameterize 164 | ParseIntError 165 | PartialEq 166 | PartialOrd 167 | powi 168 | preprocessing 169 | Preprocessing 170 | preprocessor 171 | println 172 | priv 173 | proc 174 | pthreads 175 | QuitMessage 176 | RAII 177 | randcrate 178 | READMEs 179 | rect 180 | redeclaring 181 | Refactoring 182 | refactor 183 | refactoring 184 | RefCell 185 | repr 186 | ripgrep 187 | runtime 188 | Rustacean 189 | Rustaceans 190 | rustc 191 | rustdoc 192 | rustup 193 | semver 194 | SemVer 195 | shouldn 196 | sizeof 197 | someproject 198 | someusername 199 | SpreadsheetCell 200 | sqrt 201 | stackoverflow 202 | stderr 203 | stdin 204 | Stdin 205 | stdlib 206 | stdout 207 | steveklabnik's 208 | struct 209 | Struct 210 | structs 211 | struct's 212 | Structs 213 | subdirectories 214 | subdirectory 215 | submodule 216 | submodules 217 | Submodules 218 | suboptimal 219 | subtree 220 | subtyping 221 | Supertraits 222 | That'd 223 | test's 224 | TODO 225 | toml 226 | TOML 227 | tradeoff 228 | tradeoffs 229 | TrafficLight 230 | trpl 231 | tuple 232 | tuples 233 | typeof 234 | UFCS 235 | unary 236 | Unary 237 | Uninstalling 238 | uninstall 239 | unoptimized 240 | UnsafeCell 241 | unsized 242 | unsynchronized 243 | username 244 | USERPROFILE 245 | usize 246 | UsState 247 | variable's 248 | Versioning 249 | wasn 250 | whitespace 251 | workspace 252 | workspaces 253 | Workspaces 254 | wouldn 255 | writeln 256 | WriteMessage 257 | yyyy 258 | -------------------------------------------------------------------------------- /examples/lorem.txt: -------------------------------------------------------------------------------- 1 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse at elit at sem accumsan 2 | lobortis at iaculis nibh. Sed vel arcu vitae ante porta laoreet ac nec nisl. Praesent sodales 3 | turpis lorem, ultricies ullamcorper ante accumsan et. 4 | 5 | Fusce faucibus, elit ut feugiat fermentum, risus metus accumsan nulla, sed placerat nunc velit et 6 | dui. Fusce id sapien id neque aliquet egestas non quis velit. Ut euismod, lacus ac fermentum 7 | pharetra, nunc tortor bibendum mauris, sit amet dictum diam ipsum a enim. Class aptent taciti 8 | sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. 9 | 10 | Praesent porta, est nec placerat consectetur, velit tellus fringilla erat, ut pulvinar leo leo quis 11 | urna. Vivamus mollis massa eget vehicula sollicitudin. Nulla dapibus lectus non purus euismod, eu 12 | dapibus ipsum dapibus. Pellentesque habitant morbi tristique senectus et netus et malesuada fames 13 | ac turpis egestas. 14 | 15 | Cras eu ex pharetra, semper felis non, fringilla purus. Suspendisse a pellentesque sapien, vitae 16 | tincidunt lectus. Nam suscipit posuere nunc. Etiam vitae erat mi. 17 | 18 | Donec faucibus libero quis sollicitudin viverra. Nulla eget molestie felis, eu porta nulla. 19 | Phasellus at placerat augue. Nullam quis velit at diam semper vulputate et tincidunt nibh. 20 | Curabitur ornare arcu varius feugiat gravida. Mauris a mi mauris. -------------------------------------------------------------------------------- /justfile: -------------------------------------------------------------------------------- 1 | # requires githubcontrib (https://github.com/mgechev/github-contributors-list) 2 | @update-contributors: 3 | echo 'Removing old appendix-00-contributors.md' 4 | mv src/appendix-00-contributors.md appendix-00-contributors.md.bak 5 | echo 'Downloading a list of new contributors' 6 | echo "The following is a list of contributors in alphabetical order:" > src/appendix-00-contributors.md 7 | echo "" >> src/appendix-00-contributors.md 8 | echo "" >> src/appendix-00-contributors.md 9 | githubcontrib --owner kbknapp --repo clap-book --sha master --cols 6 --format md --showlogin true --sortBy login >> src/appendix-00-contributors.md 10 | rm appendix-00-contributors.md.bak 11 | 12 | build: 13 | mdbook build 14 | 15 | clean: 16 | find . -type f -name "*.orig" -exec rm {} \; 17 | find . -type f -name "*.bk" -exec rm {} \; 18 | find . -type f -name ".*~" -exec rm {} \; 19 | 20 | @help: 21 | just -l 22 | -------------------------------------------------------------------------------- /spellcheck.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | aspell --version 4 | 5 | # Checks project markdown files for spell errors 6 | 7 | # Notes: 8 | 9 | # This script needs dictionary file ($dict_filename) with project-specific 10 | # valid words. If this file is missing, first invocation of a script generates 11 | # a file of words considered typos at the moment. User should remove real typos 12 | # from this file and leave only valid words. When script generates false 13 | # positive after source modification, new valid word should be added 14 | # to dictionary file. 15 | 16 | # Default mode of this script is interactive. Each source file is scanned for 17 | # typos. aspell opens window, suggesting fixes for each found typo. Original 18 | # files with errors will be backed up to files with format "filename.md.bak". 19 | 20 | # When running in CI, this script should be run in "list" mode (pass "list" 21 | # as first argument). In this mode script scans all files and reports found 22 | # errors. Exit code in this case depends on scan result: 23 | # 1 if any errors found, 24 | # 0 if all is clear. 25 | 26 | # Script skips words with length less than or equal to 3. This helps to avoid 27 | # some false positives. 28 | 29 | # We can consider skipping source code in markdown files (```code```) to reduce 30 | # rate of false positives, but then we lose ability to detect typos in code 31 | # comments/strings etc. 32 | 33 | shopt -s nullglob 34 | 35 | dict_filename=./dictionary.txt 36 | markdown_sources=(./src/*.md) 37 | mode="check" 38 | 39 | # aspell repeatedly modifies personal dictionary for some purpose, 40 | # so we should use a copy of our dictionary 41 | dict_path="/tmp/$dict_filename" 42 | 43 | if [[ "$1" == "list" ]]; then 44 | mode="list" 45 | fi 46 | 47 | if [[ ! -f "$dict_filename" ]]; then 48 | # Pre-check mode: generates dictionary of words aspell consider typos. 49 | # After user validates that this file contains only valid words, we can 50 | # look for typos using this dictionary and some default aspell dictionary. 51 | echo "Scanning files to generate dictionary file '$dict_filename'." 52 | echo "Please check that it doesn't contain any misspellings." 53 | 54 | echo "personal_ws-1.1 en 0 utf-8" > "$dict_filename" 55 | cat "${markdown_sources[@]}" | aspell --ignore 3 list | sort -u >> "$dict_filename" 56 | elif [[ "$mode" == "list" ]]; then 57 | # List (default) mode: scan all files, report errors 58 | declare -i retval=0 59 | 60 | cp "$dict_filename" "$dict_path" 61 | 62 | if [ ! -f $dict_path ]; then 63 | retval=1 64 | exit "$retval" 65 | fi 66 | 67 | for fname in "${markdown_sources[@]}"; do 68 | command=$(aspell --ignore 3 --personal="$dict_path" "$mode" < "$fname") 69 | if [[ -n "$command" ]]; then 70 | for error in $command; do 71 | # TODO: Find more correct way to get line number 72 | # (ideally from aspell). Now it can make some false positives, 73 | # because it is just a grep 74 | grep --with-filename --line-number --color=always "$error" "$fname" 75 | done 76 | retval=1 77 | fi 78 | done 79 | exit "$retval" 80 | elif [[ "$mode" == "check" ]]; then 81 | # Interactive mode: fix typos 82 | cp "$dict_filename" "$dict_path" 83 | 84 | if [ ! -f $dict_path ]; then 85 | retval=1 86 | exit "$retval" 87 | fi 88 | 89 | for fname in "${markdown_sources[@]}"; do 90 | aspell --ignore 3 --dont-backup --personal="$dict_path" "$mode" "$fname" 91 | done 92 | fi 93 | -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Building Command Line Utilities in Rust 2 | 3 | [Introduction](./ch00-00-introduction.md) 4 | [Before we Begin](./ch00-01-before-we-begin.md) 5 | [About This Book](./ch00-02-about.md) 6 | [Terms and Convetions](./ch00-03-terms.md) 7 | - [Building Command Line Applications](./ch01-00-command-line-applications.md) 8 | - [Major Components](./ch01-01-components.md) 9 | - [Interface](./ch01-01-00-interface.md) 10 | - [Controller](./ch01-01-01-controller.md) 11 | - [Config/Context](./ch01-01-02-config.md) 12 | - [Output](./ch01-01-03-output.md) 13 | - [Output](./ch01-01-03-00-results.md) 14 | - [Errors](./ch01-01-03-01-errors.md) 15 | - [Application](./ch01-01-04-application.md) 16 | - [Example Project `rwc`](ch01-02-rwc.md) 17 | - [Controller](./ch01-02-00-controller.md) 18 | - [Config](./ch01-02-01-config.md) 19 | - [Results](./ch01-02-02-results.md) 20 | - [Errors](./ch01-02-03-errors.md) 21 | - [Application](./ch01-02-04-application.md) 22 | ------- 23 | [Contributors](./appendix-00-contributors.md) 24 | [Contributing](./appendix-01-contributing.md) 25 | -------------------------------------------------------------------------------- /src/appendix-00-contributors.md: -------------------------------------------------------------------------------- 1 | The following is a list of contributors in alphabetical order: 2 | 3 | 4 | [kbknapp](https://github.com/kbknapp) | 5 | :---: | 6 | [kbknapp](https://github.com/kbknapp) | 7 | 8 | 9 | -------------------------------------------------------------------------------- /src/appendix-01-contributing.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | We would love issues and pull requests to the Markdown files in the src directory. The chapters we 4 | have planned but that we have not yet written appear greyed out in the sidebar of the rendered book. 5 | We would love issues with ideas for what, specifically, you'd like to see covered in those planned 6 | chapters! 7 | 8 | Our [open pull requests][pulls] are new chapters or edits that we're currently 9 | working on. We would love if you would read through those and make comments for 10 | any suggestions or corrections! 11 | 12 | [pulls]: https://github.com/kbknapp/clap-book/pulls 13 | 14 | If you're looking for ways to help that don't involve reading or writing, check 15 | out the [open issues with the M-help-wanted label][help-wanted]. These might be 16 | Rust code, frontend code, or shell scripts that would help us be more efficient 17 | or enhance the book in some way! 18 | 19 | [help-wanted]: https://github.com/kbknapp/clap-book/issues?q=is%3Aopen+is%3Aissue+label%3AM-help-wanted 20 | 21 | This repository is under the same license as Rust itself, MIT/Apache2. 22 | 23 | -------------------------------------------------------------------------------- /src/ch00-00-introduction.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | --- 4 | *Note:* This book is a work in progress in the pre-alpha stages. The source can be found [on Github] 5 | --- 6 | 7 | Welcome to the book all about building powerful, intuitive, and fast command line applications using 8 | the [Rust] programming language! This book aims to answer three distinct questions: 9 | 10 | * How should I structure and build a command line application? 11 | * How should I design the command line interface for my application? 12 | * How can I use [clap] to it's fullest potential? 13 | 14 | Each section will build on the lessons learned in previous sections, although this book does not 15 | strictly require being read linearly. The last section in particular is meant to be more of 16 | reference than a front-to-back style read. 17 | 18 | ## Contributing to the book 19 | 20 | This book is open source. If you find an error, please don’t hesitate to file an 21 | issue or send a pull request [on GitHub]. 22 | 23 | [on GitHub]: https://github.com/kbknapp/clap-book 24 | [Rust]: https://rust-lang.org/ 25 | [clap]: https://github.com/kbknapp/clap-rs -------------------------------------------------------------------------------- /src/ch00-01-before-we-begin.md: -------------------------------------------------------------------------------- 1 | # Before We Begin 2 | 3 | Throughout this book there will be various example projects and code. While most of the code can be 4 | [run online], it is strongly recommended to run it locally and experiment with various input/output. 5 | 6 | In order to run the code locally you'll need the following installed: 7 | 8 | * A [Rust compiler] with `cargo` (the latest stable release) 9 | 10 | The following items are only required to run nightly examples or to aid in running examples that 11 | target a particular compiler version: 12 | 13 | * [`rustup`] 14 | * `git` 15 | 16 | All examples from this book can be found [on Github]. 17 | 18 | [run online]: http://play.integer32.com/ 19 | [Rust compiler]: https://rust-lang.org/en-US/install.html 20 | [`rustup`]: https://rustup.rs 21 | [on Github]: https://github.com/kbknapp/clap-book/src/examples/ -------------------------------------------------------------------------------- /src/ch00-02-about.md: -------------------------------------------------------------------------------- 1 | # About 2 | 3 | This book is structured into three distinct parts. 4 | 5 | ### Part I - Building Command Line Utilities with Rust 6 | 7 | This section details building command line application in Rust. It speaks specifically about project 8 | structure and design from a high level. It also gives a small example project demonstrating the 9 | internals of a command line application. 10 | 11 | There are some notable omissions in this section, and it's by design. This section specifically does 12 | not speak about building the interface, or interface design/UX. Both of those topics are covered 13 | in extreme detail in the following sections. 14 | 15 | ### Part II - Command Line Interface Design and UX 16 | 17 | In the second section we talk specifically about designing a command line interface and the various 18 | considering for a good user experience (UX). As it turns out, small and subtle design choices can 19 | actually have a great impact on a users impression of your application or utility. 20 | 21 | This section uses a multitude of examples and builds upon the example project from the first 22 | section. 23 | 24 | ### Part III - clap-rs 25 | 26 | In the final section we dive deep into the [clap] library to give a full and complete reference of 27 | it's potential and capabilities. This section primarily uses stand alone examples to demonstrate 28 | how to use this library when building complex and powerful CLIs. 29 | 30 | [clap]: https://github.com/kbknapp/clap-rs -------------------------------------------------------------------------------- /src/ch00-03-terms.md: -------------------------------------------------------------------------------- 1 | # Terms and Conventions 2 | 3 | Before we get into the meat and potatoes of this book we need to lay out a few key terms and 4 | acronyms. 5 | 6 | * **CLI:** Stands for **C**ommand **L**ine **I**nterface and is the user facing portion of an 7 | application. This term is often incorrectly used interchangeably with "Command Line Utility" or 8 | "Command Line Application." If this book uses the term CLI, it's referring *only* to the interface. 9 | 10 | * **Command Line Application**: A program or application which runs in a terminal emulator, and 11 | typically does not have a Graphical User Interface (GUI). This term is often interchangeable with 12 | "Command Line Utility" or "Command Line Program" 13 | 14 | Inline code will be marked `like this` and multiline block code will be marked 15 | 16 | ``` 17 | Like this 18 | ``` 19 | 20 | Key terms to remember will be marked in *italics* on their first use. 21 | 22 | When running examples, the terminal will be displayed with a leading `$` if the command is meant to 23 | be run as an unprivileged user (such as your normal user account), or a `#` if the command is meant 24 | to be run as `root` or with administrative privileges. The leading character does not need to be 25 | typed when copying commands. 26 | 27 | Commands that are meant to be run on a Microsoft Windows terminal will be prefaced with a `C:\>` 28 | prompt. 29 | 30 | All commands should be able to run in either Linux, macOS, or Windows unless otherwise noted. 31 | 32 | Special notes to the reader will be annotated like this: 33 | 34 | --- 35 | *Note:* This is a special note that may explain additional details about a particular subject 36 | --- -------------------------------------------------------------------------------- /src/ch01-00-command-line-applications.md: -------------------------------------------------------------------------------- 1 | # Building Command Line Applications in Rust 2 | 3 | This section will discuss building command line applications with Rust in general. That is to say 4 | that we will be discussing how to structure the code, and some best practices or common idioms when 5 | dealing with the various parts of a command line application. 6 | 7 | The one topic that we won't discuss in this section is the interface itself. This is because there 8 | are two whole sections dedicated to that subject. 9 | 10 | We'll start by breaking down the application into common core components and discuss each in turn. 11 | After discussing the components at a high level we will build an example program to demonstrate the 12 | various techniques. 13 | 14 | All of the examples in this section can be found [on Github] under the `examples/` directory. 15 | 16 | The example program we'll be building is a replacement for the `wc` command line tool. If you're not 17 | familiar with `wc` it's a very simple program which counts the lines, bytes, and/or words of a given 18 | file or input and then outputs that information to `stdout`. 19 | 20 | [on Github]: https://github.com/kbknapp/clap-book -------------------------------------------------------------------------------- /src/ch01-01-00-interface.md: -------------------------------------------------------------------------------- 1 | # Interface 2 | 3 | The user facing portion of the application that the user interacts with is referred to as the 4 | *interface*. It can be thought of as the *language* in which the user communicates with the program. 5 | Unless your program is is a mindless top-to-bottom script, chances are good that your program needs 6 | to make decisions on what functionality to enable or disable, as well as how to accomplish certain 7 | tasks, or even what data to accomplish said tasks with. 8 | 9 | When it comes to actually adding an interface to our `rwc` program, our program will need to know 10 | what file or input to actually count. We will also add some additional functionality to `rwc` which 11 | allows the user to control the output or results. The user may only want to know how many bytes were 12 | in a particular file, and not how many lines for instance. We may also need to tell our `rwc` 13 | program how to interpret the input. 14 | 15 | All of these things must be communicated to the program in some manner. The next section focuses on 16 | interfaces in extreme detail, so I won't elaborate just yet. For now, simply remember that there are 17 | a multitude of ways in which the user *could* communicate with our program, and the difference 18 | between a well designed and powerful interface and one that is unintuitive or even laborious to use 19 | could mean the difference between your program being used, or passed over for something else. 20 | 21 | For now we'll simply note that there are two primary command line interfaces; command based, and 22 | terminal user interfaces (TUI). This book focuses on the former as it often appears to be more 23 | simple and common form, but also has fewer resources dedicated it. TUI applications can largely 24 | follow the design principals of GUI programs as the two are very similar with minor differences 25 | (such as the the potential inability to use the mouse or certain forms of input). -------------------------------------------------------------------------------- /src/ch01-01-01-controller.md: -------------------------------------------------------------------------------- 1 | # Controller 2 | 3 | The controller is the single entry and exit point of your program. It handles the initialization and 4 | exit of your program. It may not be a *thing* per se, but may just be a single *place* such as a 5 | particular function. In Rust programs it's common to use `main()` as a controller, perform the 6 | initialization, then delegate out to another function which handles the application logic. 7 | 8 | If you recall the diagram at the beginning of the chapter, there is another common variation where 9 | `main()` delegates out to `run()` immediately, and then having `run()` do all the initialization and 10 | such. `run()` would then be responsible for delegating out to some other `Application::start()` 11 | style method. The primary difference between these two approaches is where the delegation happens 12 | and who's responsible for what. More or less it's a matter of personal preference so long as 13 | everything *is* handled as concisely as possible. 14 | 15 | --- 16 | *Note:* The author of this book prefers using `main()` to initialize the application in general, and 17 | `run()` to control application logic and flow. This is the primary approach taken throughout this 18 | book. Like all things though, there is rarely *one* correct way to do things! 19 | --- 20 | 21 | This keeps your entry and exit point neat and tidy, as well as makes it easy to see where in your 22 | code things start and end. An example for a `main()` is: 23 | 24 | ```rust 25 | fn main() { 26 | // Do some initialization work... 27 | 28 | if let Err(e) = run() { 29 | // print errors neatly... 30 | 31 | // do any cleanup... 32 | 33 | ::std::process::exit(1); 34 | } 35 | } 36 | 37 | fn run() -> Result<()> { 38 | // Start the real application work... 39 | } 40 | ``` 41 | 42 | `main()` is known as the controller because it handles the program execution in serial, whereas the 43 | `run()` function handles the actual program logic. Note that `run()` returns a `Result<()>` type to 44 | indicate whether or not an error occurred, or execution was successful. This makes error handling 45 | extremely easy, as anywhere in the program if an error occurs, it can simply be propagated up back 46 | to the `run()` command, and ultimately our controller `main()` for display to the user. 47 | 48 | We'll talk more about errors shortly, as this can be a complex topic and possibly the second most 49 | important user-facing portion of an application. -------------------------------------------------------------------------------- /src/ch01-01-02-config.md: -------------------------------------------------------------------------------- 1 | # Config/Context 2 | 3 | A configuration, sometimes referred to as a context or simply by the struct `Args` is a normalized 4 | form of a combination of the user requested functionality and default functionality. The 5 | configuration contains *all* of the information that the application needs to function. 6 | 7 | The `Config` is often just a struct where each field either holds information required for the 8 | application to function, or features/functionality in which to enable/disable. Sometimes it's called 9 | `Args` because it represents a normalized version of the command line arguments passed in the by the 10 | user. By *normalized* we mean converted or deserialized in Rust types, and after resolving any sort 11 | of conflicts, overrides, requirements, or defaults. 12 | 13 | For our `rwc` program a `Config` may contain a list of files in which count, and what sorts of 14 | output the user has requested (such as all, bytes only, lines only, etc.) 15 | 16 | A `Config` may also contain fields that determine whether or not to enable other meta functionality 17 | such as whether or not to print verbose information, or what level of verbosity to use in the 18 | output. 19 | 20 | ## To Own or Borrow 21 | 22 | Something we'll need to decide about our particular `Config` struct is whether we will own or borrow 23 | the data. Unfortunately there is no *correct* answer. Typically, it's easiest to own the data. I 24 | often recommend starting with owned data, and move to borrowed data as appropriate. 25 | 26 | There are a few factors that impact our decision to use owned or borrowed data such as: 27 | 28 | * Will our program need to, or be able to run in parallel? 29 | * How long will our application need access to the information inside `Config`? 30 | * Will our application need access to *all* of the information inside `Config` at all times, or 31 | only a subset? 32 | * Will the `Config` need to be mutable throughout the applications execution, or is it only mutable 33 | during creation while all information is being normalized? 34 | 35 | For `rwc` we *could* count multiple files in parallel, or perhaps divide files into chunks and 36 | count those in parallel, but we'll start out processing files in serial for simplicity and add in 37 | paralleled portions as we advance. 38 | -------------------------------------------------------------------------------- /src/ch01-01-03-00-results.md: -------------------------------------------------------------------------------- 1 | # Results 2 | 3 | The results are exactly what they sound like, results of a particular application run. Most often 4 | it's simply text output to `stdout`. There are two common notes that should be mentioned when 5 | speaking about results: 6 | 7 | * Prefer `write!` or `writeln!` to the `std::io::Stdout` object, over `print!` and `println!` 8 | * Consider supporting multiple types of output early in the design (thinking changes to human 9 | readable output, as well as incorporating machine readable output like JSON if applicable) 10 | 11 | The second bullet is self explanatory; consider whether or not your particular output should be 12 | tweakable early in the design of the application. Tweakable means things such as substituting 13 | separators, or converting number formats. Considering the design early will allow grouping write 14 | statements, or a trait based approach instead of branches and case statements. 15 | 16 | The first bullet is more surprising to most people. The reason for preferring the `write!` macros is 17 | that it's possible for the `println!` macros to `panic!` and runtime (albeit in rare circumstances) 18 | whereas writing directly to `std::io::stdout()` (or any other `io::Write` object) allows you check 19 | for the failure and return a pretty error message. But it also has another added benefit of allowing 20 | one to write to other `io::Write` objects without changing any code. -------------------------------------------------------------------------------- /src/ch01-01-03-01-errors.md: -------------------------------------------------------------------------------- 1 | # Errors 2 | 3 | Errors are, in the opinion of the author, the most important and yet most often overlooked portion 4 | of any command line application. Without good, comprehensible and correct errors it's *very* 5 | difficult to use a program for anything other than trivial work. 6 | 7 | Errors can be divided in three categories: 8 | 9 | * Errors for end user consumption 10 | * Errors for bugs, or other application level errors that aren't meant for users 11 | * Errors meant for developers, or debugging information 12 | 13 | Bullet number three is almost not an error per-se, and more a kind of logging information, but it 14 | can often be combined with bullet number two and be an actual error. 15 | 16 | Error handling is also a topic that seems trivial in the abstract, but quickly becomes complex. 17 | There are multiple idioms and ways to tackle this subject in Rust. Each way has their pros and cons 18 | and may be determined by other reasons such as whether or not the crate in question is a library or 19 | a binary. Because this book deals with binaries, that portion of the decision is already made. We 20 | can assume that the majority of our errors will be end user consumption, which at a high level 21 | means not including gory low level details, but instead focusing on how to correct the issue at 22 | hand. 23 | 24 | There is an excellent crate called [`error-chain`] that can make this complex subject relatively 25 | trivial. Using it's calling card functionality of "error stack traces" is not a *great* fit for 26 | binaries in that it may be information overload for a user. The comparison can be made to many 27 | commercial operating systems and Linux variants; the commercial offerings will probably show a nice 28 | pretty window saying, "You don't have permission to do that", where as a Linux variant may say 29 | something along the lines of, "A particular library in use is incompatible with current user 30 | permissions on file /foo/bar/baz at address 0xE3A023A." 31 | 32 | It's a common fault, that even the author of this book falls prey to, we as programmers usually know 33 | *exactly* why something is failing. We often want to give as much information as possible to the 34 | user, because why not? The problem is it's many times only helpful to other programmers, or systems 35 | experts. It's a *far* better practice to give minimal, but correct information. If we have the extra 36 | information available, we can then give the user the option to list the additional details, and 37 | perhaps even guide them to a bug report if the problem persists. This is the best of both worlds and 38 | can be facilitated with something like a `--verbose` flag and [`error-chain`]. 39 | 40 | [`error-chain`]: https://crates.io/crates/error-chain -------------------------------------------------------------------------------- /src/ch01-01-03-output.md: -------------------------------------------------------------------------------- 1 | # Output 2 | 3 | The output is quite possibly the second most important part of the user facing code, or tied for 4 | first place. This is the output your application displays to the user, be it an error or the results 5 | of a successfully completed computation. This is why the output is typically divided into two 6 | distinct categories, results and errors. 7 | 8 | If one were to guess which is more important of the two types of output, results or errors; some 9 | would guess, "Results! Because what good is a program that returns no results?!" Which is true to 10 | an extent, but errors can prove to be a *far* greater stumbling block than results. 11 | 12 | Imagine a program, which outputs all the requested information but in a format that you're not fond 13 | of. Maybe the output is comma separated instead of tabs, and in the reverse order that you'd like 14 | to see. This may be a minor annoyance, but it's common (at least in the Linux and Unix based worlds) 15 | to combine the output of one program and shape that output with other commands and utilities. Many 16 | users may simply accept the results as given, and find ways to shift their workflow to accommodate. 17 | 18 | Unfortunately, the same cannot be said of errors. An application that gives uninformative, 19 | misleading, or worse yet incorrect error information can cause uses to abandon an application 20 | altogether. **Providing concise, comprehensible, correct errors is tantamount to a successful 21 | application.** -------------------------------------------------------------------------------- /src/ch01-01-04-application.md: -------------------------------------------------------------------------------- 1 | # Application 2 | 3 | The application does the real work, and is the meat and potatoes of the program. Because the 4 | application will vary from program to program, we won't spend a great deal of time discussing it. 5 | 6 | Rather, keep in mind that it's best to keep the application isolated yet compatible with the rest of 7 | the command line program. That is to say that it's designed with the error handling, output, and 8 | `Config` in mind. This means it will properly propagate errors up, etc. 9 | 10 | It's the opinion of the author that the application should be aware of only the `Config`, and 11 | errors. Output should work around the application's needs, not the other way around. This will keep 12 | the programs nice and modular, making them easy to reason about and control bugs that will 13 | invariably show up. 14 | 15 | In `rwc` our application will do the actual counting, managing state, etc. For example, the 16 | application will *not* be concerned with formatting output, displaying errors, parsing input, 17 | normalizing input into a `Config` or another other than counting files. 18 | -------------------------------------------------------------------------------- /src/ch01-01-components.md: -------------------------------------------------------------------------------- 1 | # Major Components 2 | 3 | Even though the use case, capabilities, and implementation of all command line programs is almost 4 | infinitely vast, they all share some common components. If we extract these components we can reuse 5 | code between our various programs. It also provides a sort of blueprint for building our 6 | applications in an efficient and effective manner. 7 | 8 | The simplified components are: 9 | 10 | * Interface 11 | * Controller 12 | * Configuration / Context 13 | * Results 14 | * Output 15 | * Errors 16 | * Application Logic 17 | 18 | The following is a diagram depicting common flow for command line applications in Rust. Don't be 19 | alarmed if not everything doesn't make perfect sense yet. All will be explained shortly! Also, it's 20 | important to note that different applications can take *slightly* different forms, but the basic 21 | components remain roughly the same. 22 | 23 | 24 | -------------------------------------------------------------------------------- /src/ch01-02-rwc.md: -------------------------------------------------------------------------------- 1 | # Meet rwc 2 | 3 | Now that we've discussed the common components of a command line program in a high level and 4 | abstract manner, we can get down to the gory details and what most consider the fun part! 5 | 6 | Implementation! 7 | 8 | The `wc` program was picked because it's simple enough to actually build while focusing on the 9 | components instead of being overwhelmed by the complexities of what it's trying to do, but also deals 10 | with enough of the common components that it'll be a great example. 11 | 12 | Since we won't be dealing with any sort of interface (yet), we'll use a static file `lorem.txt` as 13 | our input. In the next section, we'll add an interface to this tool. 14 | 15 | The contents of the `lorem.txt` file are: 16 | 17 | ``` 18 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse at elit at sem accumsan 19 | lobortis at iaculis nibh. Sed vel arcu vitae ante porta laoreet ac nec nisl. Praesent sodales 20 | turpis lorem, ultricies ullamcorper ante accumsan et. 21 | 22 | Fusce faucibus, elit ut feugiat fermentum, risus metus accumsan nulla, sed placerat nunc velit et 23 | dui. Fusce id sapien id neque aliquet egestas non quis velit. Ut euismod, lacus ac fermentum 24 | pharetra, nunc tortor bibendum mauris, sit amet dictum diam ipsum a enim. Class aptent taciti 25 | sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. 26 | 27 | Praesent porta, est nec placerat consectetur, velit tellus fringilla erat, ut pulvinar leo leo quis 28 | urna. Vivamus mollis massa eget vehicula sollicitudin. Nulla dapibus lectus non purus euismod, eu 29 | dapibus ipsum dapibus. Pellentesque habitant morbi tristique senectus et netus et malesuada fames 30 | ac turpis egestas. 31 | 32 | Cras eu ex pharetra, semper felis non, fringilla purus. Suspendisse a pellentesque sapien, vitae 33 | tincidunt lectus. Nam suscipit posuere nunc. Etiam vitae erat mi. 34 | 35 | Donec faucibus libero quis sollicitudin viverra. Nulla eget molestie felis, eu porta nulla. 36 | Phasellus at placerat augue. Nullam quis velit at diam semper vulputate et tincidunt nibh. 37 | Curabitur ornare arcu varius feugiat gravida. Mauris a mi mauris. 38 | ``` 39 | 40 | This file can also be found in the `examples/lorem.txt` or [on Github] 41 | 42 | [on Github]: https://github.com/kbknapp/clap-book/blob/master/examples/lorem.txt -------------------------------------------------------------------------------- /src/img/ch01-00-components.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/clap-rs/clap-book/9f7f5bc4b807f225c0a9a64ba14aaaa4e8307465/src/img/ch01-00-components.png -------------------------------------------------------------------------------- /style-guide.md: -------------------------------------------------------------------------------- 1 | # Style Guide 2 | 3 | ## Prose 4 | 5 | * Prefer title case for chapter/section headings, ex: `## Generating a Secret 6 | Number` rather than `## Generating a secret number`. 7 | * Prefer italics over single quotes when calling out a term, ex: `is an 8 | *associated function* of` rather than `is an ‘associated function’ of`. 9 | * When talking about a method in prose, DO NOT include the parentheses, ex: 10 | `read_line` rather than `read_line()`. 11 | * Hard wrap at 80 chars 12 | * Prefer not mixing code and not-code in one word, ex: ``Remember when we wrote 13 | `use std::io`?`` rather than ``Remember when we `use`d `std::io`?`` 14 | 15 | ## Code 16 | 17 | * Add the file name before markdown blocks to make it clear which file we're 18 | talking about, when applicable. 19 | * When making changes to code, make it clear which parts of the code changed 20 | and which stayed the same... not sure how to do this yet 21 | * Split up long lines as appropriate to keep them under 80 chars if possible 22 | * Use `bash` syntax highlighting for command line output code blocks 23 | 24 | ## Links 25 | 26 | Once all the scripts are done: 27 | 28 | * If a link shouldn't be printed, mark it to be ignored 29 | * This includes all "Chapter XX" intra-book links, which *should* be links 30 | for the HTML version 31 | * Make intra-book links and stdlib API doc links relative so they work whether 32 | the book is read offline or on docs.rust-lang.org 33 | * Use markdown links and keep in mind that they will be changed into `text at 34 | *url*` in print, so word them in a way that it reads well in that format 35 | --------------------------------------------------------------------------------