add bif debug

Author: FranBarInstance

doc/bif-debug.md

@@ -0,0 +1,214 @@
+{:debug; ... :}
+===============
+
+Outputs the schema key if debug is enabled.
+
+```html
+{:debug; data->key :}
+```
+
+For security, debug should be disabled in production. Even so, remove "debug" bifs or wrap them to prevent execution in production:
+
+```html
+{:bool; user_rol_developper >>
+    {:debug; full-schema :}
+:}
+```
+
+In the previous example, your application will be responsible for managing "user_rol_developper" or any other variable used.
+
+Stray debug bifs show an error message with a reminder to be removed in production.
+
+Modifiers:
+----------
+
+```html
+{:^debug; ... :}
+{:!debug; ... :}
+```
+### Modifier: ^ (upline)
+
+Eliminates previous whitespaces, (See "unprintable" for examples.)
+
+### Modifier: ! (not):
+
+Does not display output, except for "unprintable" if debug is active, nor does it show any error.
+
+```html
+{:!debug; this is ignored :}
+```
+It is useful to determine if debug is enabled:
+
+```html
+{:!debug; :}{:else; debug is disabled :}{:else; debug is enabled :}
+```
+
+The following does not display output or any error:
+
+```html
+{:!debug; :}
+```
+
+Although any key is ignored, it might be confusing to do this:
+
+```html
+{:!debug; data->key :}
+```
+
+No flags
+--------
+
+Enabling debug
+------------
+
+For debug to be active, a file must exist and its modification date must not be expired.
+
+The file name and expiration are set in the "schema" configuration:
+
+```text
+{
+    "config": {
+        "debug_expire": 36000,
+        "debug_file": ""
+    }
+}
+```
+
+If "debug_file" is empty or the file does not exist, debug is disabled.
+
+If the file's modification date exceeds "debug_expire" in seconds, debug is disabled.
+
+The following example enables debug for 1 hour:
+
+```text
+{
+    "config": {
+        "debug_expire": 3600,
+        "debug_file": "/tmp/enable-neutral-debug-h5hdf7sj34xp"
+    }
+}
+```
+
+Then:
+
+```text
+touch /tmp/enable-neutral-debug-h5hdf7sj34xp
+```
+
+If we want to extend the debug duration, we do again:
+
+```text
+touch /tmp/enable-neutral-debug-h5hdf7sj34xp
+```
+
+Any file name can be used, but it is a good idea to include a random part.
+
+For production, the recommended configuration is:
+
+```text
+{
+    "config": {
+        "debug_expire": 0,
+        "debug_file": ""
+    }
+}
+```
+
+Examples
+--------
+
+There are global data and keys that are available to the entire template, and local data and keys that are available in each block. "Local" information must be preceded by "local::". Some keys are always "local" such as "snippets", "locale", and others.
+
+Displays the full schema, including internal Neutral keys:
+
+```html
+{:debug; full-schema :}
+```
+
+Displays errors at this point:
+
+```html
+{:debug; __error :}
+```
+
+Displays the configuration:
+
+```html
+{:debug; config :}
+```
+
+Displays the context:
+
+```html
+{:debug; data->CONTEXT :}
+```
+
+Displays all global data:
+
+```html
+{:debug; data :}
+```
+
+Displays the variable varname:
+
+```html
+{:debug; data->varname :}
+```
+
+Displays all local data:
+
+```html
+{:debug; local::data :}
+```
+
+Displays the local variable varname:
+
+```html
+{:debug; local::data->varname :}
+```
+
+Displays the "snippets" active at this point:
+
+```html
+{:debug; local::snippets :}
+```
+
+Displays "locale":
+
+```html
+{:debug; local::locale :}
+```
+
+Displays the active translations at this point:
+
+```html
+{:debug; local::locale->trans :}
+```
+
+Displays the current language:
+
+```html
+{:debug; local::locale->current :}
+```
+
+Displays the "declare" active at this point:
+
+```html
+{:debug; local::declare :}
+```
+
+Displays the "params" active at this point:
+
+```html
+{:debug; local::params :}
+```
+
+If cache is active, the output will also be saved to the cache. If you wish to avoid this behavior, you can do so like this:
+
+```html
+{:!cache;
+    {:debug; data :}
+:}
+```
+
+---

src/bif/mod.rs

@@ -48,6 +48,7 @@ mod parse_bif_trans;
 mod parse_bif_unknown;
 mod parse_bif_var;
 mod parse_bif_obj;
+mod parse_bif_debug;
 
 mod exec_python;
 pub use exec_python::PythonExecutor;
@@ -200,6 +201,7 @@ impl<'a> Bif<'a> {
             "sum" => result = self.parse_bif_sum(),
             "trans" => result = self.parse_bif_trans(),
             "obj" => result = self.parse_bif_obj(),
+            "debug" => result = self.parse_bif_debug(),
             _ => result = self.parse_bif_unknown(),
         }
 

src/bif/parse_bif_debug.rs

@@ -0,0 +1,101 @@
+#![doc = include_str!("../../doc/bif-debug.md")]
+
+use crate::{bif::constants::*, bif::Bif, bif::BifError, constants::*};
+use std::fs;
+use std::path::Path;
+use std::time::{SystemTime, Duration};
+
+impl<'a> Bif<'a> {
+    /*
+        {:debug; data->key :}
+    */
+    pub(crate) fn parse_bif_debug(&mut self) -> Result<(), BifError> {
+        if self.mod_filter || self.mod_scope {
+            return Err(self.bif_error(BIF_ERROR_MODIFIER_NOT_ALLOWED));
+        }
+
+        let debug_enable = self.debug_enable();
+
+        if self.mod_negate {
+            if debug_enable {
+                self.out = UNPRINTABLE.to_string();
+            } else {
+                self.out = EMPTY_STRING;
+            }
+
+            return Ok(());
+        }
+
+        if !debug_enable {
+            self.out = EMPTY_STRING;
+            if self.mod_negate {
+                return Ok(());
+            } else {
+                return Err(self.bif_error("Debug is disabled. Remember to remove the bif debug in production."));
+            }
+        }
+
+        self.extract_params_code(true);
+
+        let mut schema = &self.shared.schema;
+        let mut key_name = self.code.clone();
+        if key_name.starts_with("local::") {
+            key_name = key_name.strip_prefix("local::").unwrap_or("").to_string();
+            schema = &self.shared.schema["__indir"][&self.inherit.indir];
+        }
+
+        let k = if self.code.is_empty() {
+            self.out = VERSION.to_string();
+            return Ok(());
+        } else if key_name == "full-schema" {
+            "".to_string()
+        } else {
+            format!("/{}", key_name).replace(BIF_ARRAY, "/")
+        };
+
+        self.out = match schema.pointer(&k) {
+            Some(value) => match serde_json::to_string_pretty(value) {
+                Ok(json_str) => json_str,
+                Err(e) => format!("Error formatting JSON: {}", e),
+            },
+            None => format!("Undefined: '{}'", self.code),
+        };
+
+        Ok(())
+    }
+
+    /// check if debug is enabled
+    pub(crate) fn debug_enable(&self) -> bool {
+        if self.shared.debug_file.is_empty() {
+            return false;
+        }
+
+        let path = Path::new(&self.shared.debug_file);
+
+        if !path.exists() || !path.is_file() {
+            return false;
+        }
+
+        let metadata = match fs::metadata(path) {
+            Ok(md) => md,
+            Err(_) => return false,
+        };
+
+        let modified_time = match metadata.modified() {
+            Ok(time) => time,
+            Err(_) => return false,
+        };
+
+        let now = SystemTime::now();
+
+        match now.duration_since(modified_time) {
+            Ok(duration) => duration < Duration::from_secs(self.shared.debug_expire),
+            Err(_) => false,
+        }
+    }
+}
+
+
+#[cfg(test)]
+#[path = "parse_bif_debug_tests.rs"]
+mod tests;