6 ms·

Getting started with Rust by building a tiny Markdown compiler

178 points by jesselawson 6y ago

AlchemistCamp 6y ago
I'm not completly new to Rust, but for some reason writing a Markdown has become a routine project I do in every language I'm learning. This tutorial looks fantastic. Is the layout based on a 3rd-party theme or template? I really like the presentation.
- jesselawson 6y ago
  I appreciate that you took the time to comment. Thanks for that. If you are referring to the layout of the website, it's a custom theme I wrote specifically for writing tutorials like this. It's heavily inspired by the Octopress theme for Jekyll.
- satvikpendem 6y ago
  Thanks for your Elixir tutorials! For those who don't know, Alchemist Camp is a YouTube channel and website for learning Elixir: https://alchemist.camp https://alchemist.camp
  - jesselawson 6y ago
    Wonderful, thank you!
  - deleted 6y ago
    [deleted]
einpoklum 6y ago
1. This is more of a "taste-teaser" than a tutorial in my opinion, but it's nice enough I guess. 2. Perhaps a different page for each chapter/part would have been nice. 3. I wonder how different would a C++ "taste-teaser" with the same scope and goal be. 4. I'm not a Rustian (Rustic? Rust-guy?); this seems strange to me: // Try to open the file let file = File::open(&input_filename) .expect("[ ERROR ] Failed to open file!"); why am I expecting an error? Shouldn't that keyword be "on_exception" or something?
- aaronjanse 6y ago
  > why am I expecting an error? Shouldn't that keyword be "on_exception" or something? `expect` takes an input that is either an error or a value, then turns that input into just a value. The provided string is the error message if something goes wrong (i.e. the input was an error).
  - einpoklum 6y ago
    A little counter-intuitive IMHO. But - I live with C++'s template voodoo, so I guess I can't really complain.
    - Measter 6y ago
      The way recoverable errors are signalled in Rust is through the return value, which is done using the `Result` enum. That enum is basically[0] defined like this: enum Result<T, E> { Ok(T), Err(E), } Opening a file can, of course, fail for whatever reason, so `File::open` returns a `Result`. The `expect` method in that example is one defined on `Result` which takes that result and a message string, and if it's the `Ok` variant will return the value stored that variant. If its the `Err` variant it will print the input string and start an unrecoverable [1] panic, ending the program. You would typically use `expect` (or `unwrap`, which does the same thing but without a custom message) when you either know for certain that it can't fail, or the failure condition is not something the program can recover from. [0] Full definition can be found at https://doc.rust-lang.org/std/result/enum.Result.html https://doc.rust-lang.org/std/result/enum.Result.html [1] Technically, you can catch a panic unwind [2], but it's more awkward and intended more for FFI boundaries than normal code. There's also no guarantee that the program will unwind. The compiler might have been set to abort on a panic instead of unwinding, in which case there's no unwind to catch. [2] https://doc.rust-lang.org/std/panic/fn.catch_unwind.html https://doc.rust-lang.org/std/panic/fn.catch_unwind.html
- sezna 6y ago
  it is intended to be read as “expect this to work”, or “expect this isn’t an error”
greglindahl 6y ago
I'm a bit confused by the use of the word "compiler" to refer to something that turns markdown into html.
- craftinator 6y ago
  compile [ kuh m-pahyl ] SEE SYNONYMS FOR compile ON THESAURUS.COM verb (used with object), com·piled, com·pil·ing. to put together (documents, selections, or other materials) in one book or work. https://www.dictionary.com/browse/compile https://www.dictionary.com/browse/compile
  - greglindahl 6y ago
    Thank you for posting the non-computer definition of the word. I was aware of that before I posted. A large fraction of the words I use in physics and math are not used the same way, within the field, as the generic dictionary definition.
    - mjtlittle 6y ago
      I would say the definition linked is the computer science definition. Its just commonly the case that the compilation target is some final binary, but in this case it is an html document. A lot of the terminology in CS stems from analogous similar actions we perform in real life (I saw an article a week or two ago on here listing all terms used in an instance like this) I hate it when people blindly post definitions like this without explanation, it comes off super aggressive and doesn't solve much.
      - greglindahl 6y ago
        CS history has a long history of similar pieces of software being not called compilers. Normal CS jargon has "assemblers" and "linkers", both of which might appear to be compilers according to this dictionary definition. CS history also includes things like TeX, which formats text for a variety of outputs, and was rarely called a compiler. Web browsers often include a JIT compiler for Javascript, but their text formatting system isn't usually called a compiler.
mrlonglong 6y ago
I tried Rustlings, found it a wee bit too easy to do, but I'm not quite finished yet.
gilmi 6y ago
I think the author did a great job with the format of this tutorial! It includes all the steps needed to write the app, has exercises, is neatly splitted to chapters with clear expectations and summaries for each chapter and so on. Everything needed to reduce frustration, maximize knowledge retention, and make it a nice experience as possible to the reader. Awesome work!
- jesselawson 6y ago
  Thank you for taking the time to share that. I appreciate your feedback. :)
Lapland 6y ago
Looks great, thanks for creating this!
- jesselawson 6y ago
  Thank you!
berkus 6y ago
Hmm, I see the author liberally using _filename as a variable name saying "I just use names with underscores as functions arguments names". However: In Rust, variables starting with underscores are usually indicating unused ids and if you actually forget to use it - you will not get a warning. As a tutorial material this sets very wrong mindset for the beginners. ONLY start variable with an underscore if you mean to not use it. @jesselawson - please update this.
- jesselawson 6y ago
  Thanks, berkus. I've added an [issue](https://github.com/jesselawson/rust-tiny-markdown-compiler-tutorial/issues/12 https://github.com/jesselawson/rust-tiny-markdown-compiler-t...) to track these valid concerns. I appreciate your help!

178 points by jesselawson 6y ago

I'm not completly new to Rust, but for some reason writing a Markdown has become a routine project I do in every language I'm learning. This tutorial looks fantastic. Is the layout based on a 3rd-party theme or template? I really like the presentation.

jesselawson 6y ago
I appreciate that you took the time to comment. Thanks for that. If you are referring to the layout of the website, it's a custom theme I wrote specifically for writing tutorials like this. It's heavily inspired by the Octopress theme for Jekyll.
satvikpendem 6y ago
Thanks for your Elixir tutorials! For those who don't know, Alchemist Camp is a YouTube channel and website for learning Elixir: https://alchemist.camp https://alchemist.camp
- jesselawson 6y ago
  Wonderful, thank you!
- deleted 6y ago
  [deleted]

einpoklum 6y ago

1. This is more of a "taste-teaser" than a tutorial in my opinion, but it's nice enough I guess. 2. Perhaps a different page for each chapter/part would have been nice. 3. I wonder how different would a C++ "taste-teaser" with the same scope and goal be. 4. I'm not a Rustian (Rustic? Rust-guy?); this seems strange to me: // Try to open the file let file = File::open(&input_filename) .expect("[ ERROR ] Failed to open file!"); why am I expecting an error? Shouldn't that keyword be "on_exception" or something?

aaronjanse 6y ago
> why am I expecting an error? Shouldn't that keyword be "on_exception" or something? `expect` takes an input that is either an error or a value, then turns that input into just a value. The provided string is the error message if something goes wrong (i.e. the input was an error).
- einpoklum 6y ago
  A little counter-intuitive IMHO. But - I live with C++'s template voodoo, so I guess I can't really complain.
  - Measter 6y ago
    The way recoverable errors are signalled in Rust is through the return value, which is done using the `Result` enum. That enum is basically[0] defined like this: enum Result<T, E> { Ok(T), Err(E), } Opening a file can, of course, fail for whatever reason, so `File::open` returns a `Result`. The `expect` method in that example is one defined on `Result` which takes that result and a message string, and if it's the `Ok` variant will return the value stored that variant. If its the `Err` variant it will print the input string and start an unrecoverable [1] panic, ending the program. You would typically use `expect` (or `unwrap`, which does the same thing but without a custom message) when you either know for certain that it can't fail, or the failure condition is not something the program can recover from. [0] Full definition can be found at https://doc.rust-lang.org/std/result/enum.Result.html https://doc.rust-lang.org/std/result/enum.Result.html [1] Technically, you can catch a panic unwind [2], but it's more awkward and intended more for FFI boundaries than normal code. There's also no guarantee that the program will unwind. The compiler might have been set to abort on a panic instead of unwinding, in which case there's no unwind to catch. [2] https://doc.rust-lang.org/std/panic/fn.catch_unwind.html https://doc.rust-lang.org/std/panic/fn.catch_unwind.html
sezna 6y ago
it is intended to be read as “expect this to work”, or “expect this isn’t an error”

greglindahl 6y ago

I'm a bit confused by the use of the word "compiler" to refer to something that turns markdown into html.

craftinator 6y ago
compile [ kuh m-pahyl ] SEE SYNONYMS FOR compile ON THESAURUS.COM verb (used with object), com·piled, com·pil·ing. to put together (documents, selections, or other materials) in one book or work. https://www.dictionary.com/browse/compile https://www.dictionary.com/browse/compile
- greglindahl 6y ago
  Thank you for posting the non-computer definition of the word. I was aware of that before I posted. A large fraction of the words I use in physics and math are not used the same way, within the field, as the generic dictionary definition.
  - mjtlittle 6y ago
    I would say the definition linked is the computer science definition. Its just commonly the case that the compilation target is some final binary, but in this case it is an html document. A lot of the terminology in CS stems from analogous similar actions we perform in real life (I saw an article a week or two ago on here listing all terms used in an instance like this) I hate it when people blindly post definitions like this without explanation, it comes off super aggressive and doesn't solve much.
    - greglindahl 6y ago
      CS history has a long history of similar pieces of software being not called compilers. Normal CS jargon has "assemblers" and "linkers", both of which might appear to be compilers according to this dictionary definition. CS history also includes things like TeX, which formats text for a variety of outputs, and was rarely called a compiler. Web browsers often include a JIT compiler for Javascript, but their text formatting system isn't usually called a compiler.

mrlonglong 6y ago

I tried Rustlings, found it a wee bit too easy to do, but I'm not quite finished yet.

gilmi 6y ago

I think the author did a great job with the format of this tutorial! It includes all the steps needed to write the app, has exercises, is neatly splitted to chapters with clear expectations and summaries for each chapter and so on. Everything needed to reduce frustration, maximize knowledge retention, and make it a nice experience as possible to the reader. Awesome work!

jesselawson 6y ago
Thank you for taking the time to share that. I appreciate your feedback. :)

Lapland 6y ago

Looks great, thanks for creating this!

jesselawson 6y ago
Thank you!

berkus 6y ago

Hmm, I see the author liberally using _filename as a variable name saying "I just use names with underscores as functions arguments names". However: In Rust, variables starting with underscores are usually indicating unused ids and if you actually forget to use it - you will not get a warning. As a tutorial material this sets very wrong mindset for the beginners. ONLY start variable with an underscore if you mean to not use it. @jesselawson - please update this.

jesselawson 6y ago
Thanks, berkus. I've added an [issue](https://github.com/jesselawson/rust-tiny-markdown-compiler-tutorial/issues/12 https://github.com/jesselawson/rust-tiny-markdown-compiler-t...) to track these valid concerns. I appreciate your help!