docs: Deprecate SCOPE_REPO for removal

Author: CosmicHorrorDev

src/html.rs

@@ -3,8 +3,8 @@ use crate::easy::{HighlightFile, HighlightLines};
 use crate::escape::Escape;
 use crate::highlighting::{Color, FontStyle, Style, Theme};
 use crate::parsing::{
-    BasicScopeStackOp, ParseState, Scope, ScopeStack, ScopeStackOp, SyntaxReference, SyntaxSet,
-    SCOPE_REPO,
+    lock_global_scope_repo, BasicScopeStackOp, ParseState, Scope, ScopeStack, ScopeStackOp,
+    SyntaxReference, SyntaxSet,
 };
 use crate::util::LinesWithEndings;
 use crate::Error;
@@ -242,7 +242,7 @@ pub enum ClassStyle {
 }
 
 fn scope_to_classes(s: &mut String, scope: Scope, style: ClassStyle) {
-    let repo = SCOPE_REPO.lock().unwrap();
+    let repo = lock_global_scope_repo();
     for i in 0..(scope.len()) {
         let atom = scope.atom_at(i as usize);
         let atom_s = repo.atom_str(atom);
@@ -260,7 +260,7 @@ fn scope_to_classes(s: &mut String, scope: Scope, style: ClassStyle) {
 }
 
 fn scope_to_selector(s: &mut String, scope: Scope, style: ClassStyle) {
-    let repo = SCOPE_REPO.lock().unwrap();
+    let repo = lock_global_scope_repo();
     for i in 0..(scope.len()) {
         let atom = scope.atom_at(i as usize);
         let atom_s = repo.atom_str(atom);

src/parsing/scope.rs

@@ -4,7 +4,7 @@ use std::collections::HashMap;
 use std::fmt;
 use std::mem;
 use std::str::FromStr;
-use std::sync::Mutex;
+use std::sync::{Mutex, MutexGuard};
 
 use once_cell::sync::Lazy;
 use serde::de::{Deserialize, Deserializer, Error, Visitor};
@@ -30,9 +30,23 @@ pub const ATOM_LEN_BITS: u16 = 3;
 /// Ths shouldn't be necessary for you to use. See the [`ScopeRepository`] docs.
 ///
 /// [`ScopeRepository`]: struct.ScopeRepository.html
+#[deprecated(
+    since = "5.3.0",
+    note = "\
+    Deprecated in anticipation of removal in the next semver-breaking release under the \
+    justification that it's incredibly niche functionality to expose. If you rely on this \
+    functionality then please express your particular use-case in the github issue: \
+    https://github.com/trishume/syntect/issues/575\
+    "
+)]
 pub static SCOPE_REPO: Lazy<Mutex<ScopeRepository>> =
     Lazy::new(|| Mutex::new(ScopeRepository::new()));
 
+pub(crate) fn lock_global_scope_repo() -> MutexGuard<'static, ScopeRepository> {
+    #[allow(deprecated)]
+    SCOPE_REPO.lock().unwrap()
+}
+
 /// A hierarchy of atoms with semi-standardized names used to accord semantic information to a
 /// specific piece of text.
 ///
@@ -221,7 +235,7 @@ impl Scope {
     ///
     /// Example: `Scope::new("meta.rails.controller")`
     pub fn new(s: &str) -> Result<Scope, ParseScopeError> {
-        let mut repo = SCOPE_REPO.lock().unwrap();
+        let mut repo = lock_global_scope_repo();
         repo.build(s.trim())
     }
 
@@ -266,7 +280,7 @@ impl Scope {
     ///
     /// This requires locking a global repo and shouldn't be done frequently.
     pub fn build_string(self) -> String {
-        let repo = SCOPE_REPO.lock().unwrap();
+        let repo = lock_global_scope_repo();
         repo.to_string(self)
     }
 

src/parsing/yaml_load.rs

@@ -95,7 +95,7 @@ impl SyntaxDefinition {
             return Err(ParseSyntaxError::EmptyFile);
         }
         let doc = &docs[0];
-        let mut scope_repo = SCOPE_REPO.lock().unwrap();
+        let mut scope_repo = lock_global_scope_repo();
         SyntaxDefinition::parse_top_level(
             doc,
             scope_repo.deref_mut(),