Built in dumps

benches/loading.rs

@@ -14,6 +14,14 @@ fn bench_load_syntax_dump(b: &mut Bencher) {
     });
 }
 
+#[bench]
+fn bench_load_internal_dump(b: &mut Bencher) {
+    b.iter(|| {
+        let ps = PackageSet::load_defaults_newlines();
+        test::black_box(&ps);
+    });
+}
+
 #[bench]
 fn bench_load_syntaxes(b: &mut Bencher) {
     b.iter(|| {

examples/syncat.rs

@@ -12,7 +12,7 @@ use std::path::Path;
 use std::fs::File;
 
 fn main() {
-    let ps = PackageSet::load_from_folder("testdata/Packages").unwrap();
+    let ps = PackageSet::load_defaults_nonewlines();
     let highlighter = Highlighter::new(PackageSet::get_theme("testdata/spacegray/base16-ocean.\
                                                               dark.tmTheme")
         .unwrap());

src/dumps.rs

@@ -6,6 +6,33 @@ use package_set::PackageSet;
 use std::path::Path;
 
 impl PackageSet {
+    /// Instantiates a new package set from a binary dump of
+    /// Sublime Text's default open source syntax definitions and then links it.
+    /// These dumps are included in this library's binary for convenience.
+    /// This method loads the version for parsing line strings with no `\n` characters at the end.
+    ///
+    /// This is the recommended way of creating a package set for
+    /// non-advanced use cases. It is also significantly faster than loading the YAML files.
+    ///
+    /// Note that you can load additional syntaxes after doing this,
+    /// you'll just have to link again. If you want you can even
+    /// use the fact that SyntaxDefinitions are serializable with
+    /// the bincode crate to cache dumps of additional syntaxes yourself.
+    pub fn load_defaults_nonewlines() -> PackageSet {
+        let mut ps = Self::from_binary(include_bytes!("../assets/default_nonewlines.packdump"));
+        ps.link_syntaxes();
+        ps
+    }
+
+    /// Same as `load_defaults_nonewlines` but for parsing line strings with newlines at the end.
+    /// These are separate methods because thanks to linker garbage collection, only the serialized
+    /// dumps for the method(s) you call will be included in the binary (each is ~1MB for now).
+    pub fn load_defaults_newlines() -> PackageSet {
+        let mut ps = Self::from_binary(include_bytes!("../assets/default_newlines.packdump"));
+        ps.link_syntaxes();
+        ps
+    }
+
     pub fn dump_binary(&self) -> Vec<u8> {
         assert!(!self.is_linked);
         encode(self, SizeLimit::Infinite).unwrap()
@@ -18,8 +45,8 @@ impl PackageSet {
 
     /// Returns a fully loaded and linked package set from
     /// a binary dump. Panics if the dump is invalid.
-    pub fn from_binary(v: Vec<u8>) -> PackageSet {
-        let mut ps: PackageSet = decode(&v[..]).unwrap();
+    pub fn from_binary(v: &[u8]) -> PackageSet {
+        let mut ps: PackageSet = decode(v).unwrap();
         ps.link_syntaxes();
         ps
     }
@@ -42,7 +69,7 @@ mod tests {
         ps.load_syntaxes("testdata/Packages", false).unwrap();
 
         let bin = ps.dump_binary();
-        let ps2 = PackageSet::from_binary(bin);
+        let ps2 = PackageSet::from_binary(&bin[..]);
         assert_eq!(ps.syntaxes.len(), ps2.syntaxes.len());
     }
 }

src/package_set.rs

@@ -15,6 +15,13 @@ use std::mem;
 use std::rc::Rc;
 use std::ascii::AsciiExt;
 
+/// A package set holds a bunch of syntaxes and manages
+/// loading them and the crucial operation of *linking*.
+///
+/// Linking replaces the references between syntaxes with direct
+/// pointers. See `link_syntaxes` for more.
+/// Linking, followed by adding more unlinked syntaxes with `load_syntaxes`
+/// and then linking again is allowed.
 #[derive(Debug, RustcEncodable, RustcDecodable)]
 pub struct PackageSet {
     pub syntaxes: Vec<SyntaxDefinition>,
@@ -152,6 +159,7 @@ impl PackageSet {
     /// It is necessary to do this before parsing anything with these syntaxes.
     /// However, it is not possible to serialize a package set that has been linked,
     /// which is why it isn't done by default, except by the load_from_folder constructor.
+    /// This operation is idempotent, but takes time even on already linked package sets.
     pub fn link_syntaxes(&mut self) {
         for syntax in self.syntaxes.iter() {
             for (_, ref context_ptr) in syntax.contexts.iter() {