Merge pull request #22 from jkuczm/paclet

jkuczm · web-flow · commit e6d6f53ad0b8 · 2019-01-13T17:15:57.000+01:00
Paclet + sub-package
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,4 @@
 .directory
 /build
 /private
-/buildScripts/build.properties
-/SyntaxAnnotations.zip
+/SyntaxAnnotations-*.*.*.paclet
diff --git a/BootstrapInstall.m b/BootstrapInstall.m
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2015 - 2016 Jakub Kuczmarski <Jakub.Kuczmarski@gmail.com>
+Copyright (c) 2015 - 2019 Jakub Kuczmarski <Jakub.Kuczmarski@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/NoInstall.m b/NoInstall.m
@@ -0,0 +1,11 @@
+(* ::Package:: *)
+
+
+Internal`InheritedBlock[{BeginPackage},
+	Unprotect@BeginPackage;
+	(*	If package is loaded through NoInstall.m it'll be loaded as package
+		with ordinary "top-level" context. *)
+	BeginPackage@"`SyntaxAnnotations`" := BeginPackage@"SyntaxAnnotations`";
+	Protect@BeginPackage;
+	Import@"https://raw.githubusercontent.com/jkuczm/MathematicaSyntaxAnnotations/master/SyntaxAnnotations/SyntaxAnnotations.m"
+]
diff --git a/PacletInfo.m b/PacletInfo.m
@@ -1,15 +1,18 @@
 (* Paclet Info File *)
 
-(* created 2016/10/21*)
+(* created 2019/01/11*)
 
 Paclet[
     Name -> "SyntaxAnnotations",
-    Version -> "0.2.1",
+    Version -> "0.2.2",
     MathematicaVersion -> "6+",
     Description -> "Annotate syntax elements at box level",
     Creator -> "Jakub Kuczmarski",
     Extensions -> 
         {
+            {"Kernel", "Context" -> 
+                {"SyntaxAnnotations`"}
+            }, 
             {"Documentation", Language -> "English"}
         }
 ]
diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 # Syntax Annotations
 
-[![releases](http://img.shields.io/github/release/jkuczm/MathematicaSyntaxAnnotations.svg)](https://github.com/jkuczm/MathematicaSyntaxAnnotations/releases)
-[![SemVer 2.0.0](http://img.shields.io/badge/SemVer-2.0.0-brightgreen.svg)](http://semver.org/spec/v2.0.0.html)
-[![license MIT](http://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jkuczm/MathematicaSyntaxAnnotations/blob/master/LICENSE)
-[![Mathematica 8.0 - 11.0](http://img.shields.io/badge/Mathematica-8.0 -- 11.0-brightgreen.svg)](#compatibility)
+[![releases](https://img.shields.io/github/release/jkuczm/MathematicaSyntaxAnnotations.svg)](https://github.com/jkuczm/MathematicaSyntaxAnnotations/releases)
+[![Mathematica 8.0 - 11.0](https://img.shields.io/badge/Mathematica-8.0_--_11.0-brightgreen.svg)](#compatibility)
+[![license MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jkuczm/MathematicaSyntaxAnnotations/blob/master/LICENSE)
+[![SemVer 2.0.0](https://img.shields.io/badge/SemVer-2.0.0-brightgreen.svg)](http://semver.org/spec/v2.0.0.html)
 
 
 Annotate syntax elements at box level.
@@ -17,6 +17,7 @@ Annotate syntax elements at box level.
 * [Compatibility](#compatibility)
 * [Bugs and requests](#bugs-and-requests)
 * [Contributing](#contributing)
+* [Usage in other packages](#usage-in-other-packages)
 * [License](#license)
 * [Versioning](#versioning)
 
@@ -35,36 +36,51 @@ on Mathematica Stack Exchange.
 
 ### Automatic installation
 
-To install SyntaxAnnotations package evaluate:
+To install newest version of SyntaxAnnotations package,
+in *Mathematica* version 10 or newer, evaluate following code:
 ```Mathematica
-Import["https://raw.githubusercontent.com/jkuczm/MathematicaSyntaxAnnotations/master/BootstrapInstall.m"]
+PacletInstall@"http://github.com/jkuczm/MathematicaSyntaxAnnotations/releases/download/v0.2.2/SyntaxAnnotations-0.2.2.paclet"
 ```
 
-Note that this will also install
-[ProjectInstaller](https://github.com/lshifr/ProjectInstaller)
-package, if you don't have it already installed.
+Note that above requires allowing *Mathematica* to use the Internet.
 
-To load SyntaxAnnotations package evaluate: ``Needs["SyntaxAnnotations`"]``.
+To load SyntaxAnnotations package evaluate:
+```Mathematica
+Needs@"SyntaxAnnotations`"
+```
+
+To uninstall SyntaxAnnotations package evaluate:
+```Mathematica
+PacletUninstall@"SyntaxAnnotations"
+```
 
 
 ### Manual installation
 
-1. Download latest released
-   [SyntaxAnnotations.zip](https://github.com/jkuczm/MathematicaSyntaxAnnotations/releases/download/v0.2.1/SyntaxAnnotations.zip)
-   file.
+If in your setup *Mathematica* doesn't have Internet access,
+or you're using version older than 10, download
+[SyntaxAnnotations.0.2.2.paclet](https://github.com/jkuczm/MathematicaSyntaxAnnotations/releases/download/v0.2.2/SyntaxAnnotations-0.2.2.paclet)
+file and evaluate `PacletInstall` with path to downloaded file:
+```Mathematica
+PacletInstall@"path/to/downloaded/SyntaxAnnotations.0.2.2.paclet"
+```
 
-2. Extract downloaded `SyntaxAnnotations.zip` to any directory which is on
-   *Mathematica* `$Path`, e.g. to one obtained by evaluating
-   `FileNameJoin[{$UserBaseDirectory,"Applications"}]`.
+To load SyntaxAnnotations package evaluate:
+```Mathematica
+Needs@"SyntaxAnnotations`"
+```
 
-3. To load the package evaluate: ``Needs["SyntaxAnnotations`"]``
+To uninstall SyntaxAnnotations package evaluate:
+```Mathematica
+PacletUninstall@"SyntaxAnnotations"
+```
 
 
 ### No installation
 
 To use package directly from the Web, without installation, evaluate:
 ```Mathematica
-Import["https://raw.githubusercontent.com/jkuczm/MathematicaSyntaxAnnotations/master/SyntaxAnnotations/SyntaxAnnotations.m"]
+Import@"https://raw.githubusercontent.com/jkuczm/MathematicaSyntaxAnnotations/master/NoInstall.m"
 ```
 
 
@@ -77,8 +93,9 @@ Package is tested with all *Mathematica* major and minor versions from 8.0 to
 11.0 on Linux. Since it doesn't contain any OS specific code it should work
 with above versions on all operating systems.
 
-There's also no obvious reason for package not to work on earlier (6.0+)
-versions of *Mathematica*.
+There's also no obvious reason for package not to work on older (6.0+)
+and newer (11.1+) versions of *Mathematica*,
+but it was not tested with these versions.
 
 
 
@@ -93,13 +110,55 @@ If you find any bugs or have feature request please create an
 
 Feel free to fork and send pull requests.
 
-If you want to use Ant scripts from this repository you will also need to
-install [WWBCommon](https://github.com/jkuczm/WWBCommon) project.
-
 All contributions are welcome!
 
 
 
+## Usage in other packages
+
+There are two ways to use SyntaxAnnotations with your own package.
+
+First is to require users, of your package, to install SyntaxAnnotations
+separately. Your package can then load it, as any other external package, using
+``Get@"SyntaxAnnotations`"``. Be aware that if your package requires specific
+version of SyntaxAnnotations and user wants to use other package requiring
+different version of SyntaxAnnotations it may lead to a version conflict.
+
+Second way is to include specific version of SyntaxAnnotations as sub-package
+of your package. To do it, simply put `SyntaxAnnotations.m` file inside main
+directory of your package. And load it using ``Get@"`SyntaxAnnotations`"``
+(note the grave accent character at the beginning of string) somewhere inside
+main context of your package.
+
+Directory structure of ``YourPackage` `` can, for example, look like this:
+
+```
+YourPackage
+├── Kernel
+│   └── init.m
+├── SyntaxAnnotations.m
+└── YourPackage.m
+```
+
+and `YourPackage.m` file:
+
+```Mathematica
+BeginPackage@"YourPackage`"
+(* Public symbols usage *)
+Get@"`SyntaxAnnotations`"
+Begin@"`Private`"
+(* Implementation *)
+End[]
+EndPackage[]
+```
+
+This way specific version of SyntaxAnnotations package, distributed with your
+package, will be loaded as ``YourPackage`SyntaxAnnotations` ``, and will be
+completely independent of other versions of SyntaxAnnotations possibly used by
+user of your package.
+
+
+
 ## License
 
 This package is released under
diff --git a/SyntaxAnnotations/Kernel/init.m b/SyntaxAnnotations/Kernel/init.m
@@ -1,3 +1,10 @@
 (* Mathematica Init File *)
 
-Get[ "SyntaxAnnotations`SyntaxAnnotations`"]
+Internal`InheritedBlock[{BeginPackage},
+	Unprotect@BeginPackage;
+	(*	If package is loaded through init.m it'll be loaded as package with
+		ordinary "top-level" context. *)
+	BeginPackage@"`SyntaxAnnotations`" := BeginPackage@"SyntaxAnnotations`";
+	Protect@BeginPackage;
+	Get@"SyntaxAnnotations`SyntaxAnnotations`"
+]
diff --git a/SyntaxAnnotations/SyntaxAnnotations.m b/SyntaxAnnotations/SyntaxAnnotations.m
@@ -1,6 +1,17 @@
 (* ::Package:: *)
 
-BeginPackage["SyntaxAnnotations`"]
+(* SyntaxAnnotations package
+
+Copyright (c) 2015 - 2019 Jakub Kuczmarski <Jakub.Kuczmarski@gmail.com>
+Released under The MIT License
+https://github.com/jkuczm/MathematicaSyntaxAnnotations/blob/master/LICENSE *)
+
+
+(*	Begining of package context with ` is intentionall it allows loading
+	SyntaxAnnotations as a sub-package. Apropriate steps to load package with
+	SyntaxAnnotations` as "top level" context are taken in Kernel/init.m.
+	This is inspired by system used in https://github.com/szhorvat/LTemplate *)
+BeginPackage["`SyntaxAnnotations`"]
 
 
 Unprotect["`*"]
diff --git a/buildScripts/deploy.xml b/buildScripts/deploy.xml
diff --git a/buildScripts/project.properties b/buildScripts/project.properties

Original file line number	Diff line number	Diff line change
`@@ -1,15 +1,18 @@`
`1`	`1`	`(* Paclet Info File *)`
`2`	`2`
`3`		`-(* created 2016/10/21*)`
	`3`	`+(* created 2019/01/11*)`
`4`	`4`
`5`	`5`	`Paclet[`
`6`	`6`	`Name -> "SyntaxAnnotations",`
`7`		`- Version -> "0.2.1",`
	`7`	`+ Version -> "0.2.2",`
`8`	`8`	`MathematicaVersion -> "6+",`
`9`	`9`	`Description -> "Annotate syntax elements at box level",`
`10`	`10`	`Creator -> "Jakub Kuczmarski",`
`11`	`11`	`Extensions ->`
`12`	`12`	`{`
	`13`	`+ {"Kernel", "Context" ->`
	`14`	+ {"SyntaxAnnotations`"}
	`15`	`+ },`
`13`	`16`	`{"Documentation", Language -> "English"}`
`14`	`17`	`}`
`15`	`18`	`]`