Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Issues in the quick start guide #525

Open
6 tasks
agluszak opened this issue Feb 5, 2024 · 2 comments
Open
6 tasks

Issues in the quick start guide #525

agluszak opened this issue Feb 5, 2024 · 2 comments

Comments

@agluszak
Copy link

agluszak commented Feb 5, 2024

I've heard about this library from a /r/rust announcement so I decided to go through the quick start guide, but I found some issues in it.

  • here the "@" syntax is mentioned, but it has not been introduced yet. Also there's a link to a non-existent doc called "Creating an application"
  • Formatting is inconsistent. Sometimes there is a space between rdl! and {, sometimes there isn't
  • "rdl! does not care about types, it only does processing at the syntax level, so it is not only widgets that can use it." - this notice is not clear to me. What does it mean that "rdl!" does not care about types? Procedural macros in general are unable to reason about types.
  • "When your expression is a structure literal, rdl! will create an object through the Declare trait, which requires that the type of the object you create must inherit or implement the Declare trait." What does it mean that a type "inherits" a trait?
  • At this point it is not clear to me why Label is created with ::new and not via the Declare trait
  • Idk if it's a problem with the wording, or with the design of rdl, but you say that "$counter.write() expand[s] to counter.write()", however it actually shrinks, because the result is shorter ;)

to be continued...

@wjian23
Copy link
Contributor

wjian23 commented Feb 6, 2024

Thank you for your favor @agluszak , we'll improve the writing later. And here I try to answer some of your confusion.

  1. the rdl! is a macro to achieve the syntax, it just translate the ribir declare syntax to rust syntax, so we say it does not care about types, however if the type not match, it'll compile failed.
  2. there is two kind of value can be recognize under the rdl! macro:
    • structure literal. when rdl! with structure literal, we'll expand to declare a widget by DeclareBuilder, e.g.:
      rdl!{ Counter { cnt: 0 } }
      will be expand to something like
      Counter::declare_builder().cnt(0).widget_build(ctx!())
    • the other expression. when rdl! with other expression, it will declare a widget from the expression's result, e.g.:
    fn build_counter(cnt: u32) -> impl WidgetBuilder {
        fn_widget! { rdl! { Counter {cnt: cnt} } }
    }
    
    rdl!{ let a = 0;  build_counter(a) }
    
    it's just like to declare the expression's result as a widget
    { let a = 0; build_counter(a) }
    
    this will be helpful for you to do some calculate.
  3. the $xxx.write() not only be expand to counter.write() simple, the framework do more work here. the $xxx may probability be pass to move Closure, the framework will auto clone the $xxx before move, so it's different to use like xxx.write(). e.g.:
pub fn test() -> impl WidgetBuilder {
  fn_widget! {
    let cnt = Stateful::new(0);
    @FilledButton {
      // on_tap: {
      //   let cnt = cnt.clone_writer();
      //   move |_| cnt.write() += 1
      // }
      on_tap: move |_| *$cnt.write() += 1,

      // on_tap: {
      //   let cnt = cnt.clone_writer();
      //   move |_| cnt.write() += 2
      // }
      on_double_tap: move |_| *$cnt.write() += 2;
      @{ Label::new("Inc") }
    }
  }
}

@M-Adoo
Copy link
Collaborator

M-Adoo commented Feb 6, 2024

@agluszak
Thank you for your feedback. The issues with the broken links have been addressed and the example code has been formatted in #526.

@wjian23 has provided explanations for the other issues. Regarding the Label, there are two key points to consider:

  • Ribir supports the use of any Rust expression, as long as the result meets the type requirement for a declarative node.
  • In the future, we plan to eliminate the Label entirely and directly support String. The syntax @ { Label::new("Increment") } will be replaced by @ { "Increment" }.

Please feel free to reach out if you have any further questions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants