canvasapi/
parameters.rs

1//! Parameters that can be passed with a request.
2//!
3//! # Example
4//!
5//! For example, the `EnrollmentType` is added as a parameter, which will return only the students
6//! for the specific course.
7//! To know which parameters can be used for a request, the official Canvas LMS API documentation
8//! needs to be consulted.
9//!
10//! ```
11//! # use canvasapi::prelude::*;
12//! # #[tokio::test]
13//! # async fn parameter_test() {
14//! #   dotenv::dotenv().ok();
15//! #   let base_url = std::env::var("CANVAS_BASE_URL").unwrap();
16//! #   let cvs_token = std::env::var("CANAVS_ACCESS_TOKEN").unwrap();
17//! #   let canvas = CanvasInformation::new(&base_url, &cvs_token);
18//! #   let course = Canvas::get_course(13369)
19//! #       .unwrap()
20//! #       .fetch(&canvas)
21//! #       .await
22//! #       .unwrap()
23//! #       .inner();
24//!
25//! let students = course
26//!     .get_users()
27//!     .unwrap()
28//!     .add_parameter(EnrollmentType::Student)
29//!     .fetch(&canvas).await.unwrap().inner();
30//! #   }
31//! ```
32
33/// Parameter that can be added to a request.
34pub struct RequestParameter {
35    pub name: String,
36    pub value: String,
37}
38
39macro_rules! api_parameter {
40    (
41        $(#[$outer:meta])*
42        $name:ident => $name_output:expr,
43        $(
44            $(#[$option_outer:meta])*
45            $option:ident => $option_output:expr ,
46        )* $(,)?
47    ) => {
48        $(#[$outer])*
49        pub enum $name {
50            $(
51                $(#[$option_outer])*
52                $option,
53            )*
54        }
55
56        impl From<$name> for RequestParameter {
57            fn from(value: $name) -> Self {
58                RequestParameter {
59                    name: $name_output.into(),
60                    value: match value {
61                        $(<$name>::$option => $option_output,)*
62                    }.into(),
63                }
64            }
65        }
66
67        impl std::str::FromStr for $name {
68            type Err = ();
69
70            fn from_str(s: &str) -> Result<Self, Self::Err> {
71                match s {
72                    $($option_output => Ok(Self::$option),)*
73                    _ => Err(()),
74                }
75            }
76        }
77    };
78
79    (
80        $(#[$outer:meta])*
81        $name:ident => $name_output:expr
82    ) => {
83        $(#[$outer])*
84        pub struct $name<'i>(pub &'i str);
85
86        impl<'i> From<$name<'i>> for RequestParameter {
87            fn from(value: $name) -> Self {
88                RequestParameter {
89                    name: $name_output.into(),
90                    value: value.0.into(),
91                }
92            }
93        }
94    };
95}
96
97api_parameter! {
98    /// If this parameter is given and it corresponds to a user in the course, the page parameter
99    /// will be ignored and the page containing the specified user will be returned instead.
100    UserId => "user_id"
101}
102
103api_parameter! {
104    #[derive(Debug)]
105    /// Parameter to specify the enrollment type of a user.
106    EnrollmentType => "enrollment_type[]",
107    Teacher => "teacher",
108    Student => "student",
109    StudentView => "student_view",
110    TA => "ta",
111    Observer => "observer",
112    Designer => "designer",
113}
114
115api_parameter! {
116    #[derive(Debug)]
117    /// Parameter to specify on wich field the output is sorted.
118    SortOn => "sort",
119    Username => "username",
120    LastLogin => "last_login",
121    Email => "email",
122    SisId => "sis_id",
123}
124
125api_parameter! {
126    EnrollmentState => "enrollment_state[]",
127    Active => "active",
128    Invited => "invited",
129    Rejected => "rejected",
130    Completed => "completed",
131    Inactive => "inactive",
132    InvitedOrPending => "invited_or_pending",
133}
134
135api_parameter! {
136    Include => "include[]",
137    Enrollments => "enrollments",
138    Locked => "locked",
139    AvatarUrl => "avatar_url",
140    TestStudent => "test_student",
141    Bio => "bio",
142    CustomLinks => "custom_links",
143    CurrentGradingPeriodScores => "current_grading_period_scores",
144    Uuid => "uuid",
145    NeedsGradingCount => "needs_grading_count",
146    SyllabusBody => "syllabus_body",
147    PublicDescription => "public_description",
148    TotalScores => "total_scores",
149    /// The information for the enrollment term for each course is returned.
150    Term => "term",
151    Account => "account",
152    CourseProgress => "course_progress",
153    Sections => "sections",
154    StorageQuotaUsedMb => "storage_quota_used_mb",
155    TotalStudents => "total_students",
156    PassbackStatus => "passback_status",
157    Favorites => "favorites",
158    Teachers => "teachers",
159    ObservedUsers => "observed_users",
160    CourseImage => "course_image",
161    Concluded => "concluded",
162}
canvasapi/parameters.rs

canvasapi/
parameters.rs
