Skip to content

Commit

Permalink
Merge branch 'refs/heads/release/1.0.1' into 1.x
Browse files Browse the repository at this point in the history
  • Loading branch information
beccadax committed Jul 31, 2013
2 parents 8542aba + a1e31fe commit c1ead1b
Show file tree
Hide file tree
Showing 9 changed files with 206 additions and 9 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
xcuserdata
114 changes: 114 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
SyntaxKit
========

SyntaxKit is a Cocoa framework with the following features:

* Syntax highlighting
* Basic code editing, particularly concerning indentation
* On-screen line numbering

The syntax highlighting and code editing features are based on [UKSyntaxColoredTextViewController][uksyntax], and the line numbering is based on [NoodleLineNumberView][noodleline]. However, both of these have been extensively modified, and are no longer fully compatible with the original versions.

Usage
----

1. In your nib file, drag an `NSTextView` into your window.
2. Drag an Object into the "Objects" section of the Interface Builder dock and set its class to `ASKSyntaxViewController`.
3. Connect your Syntax View Controller's `view` outlet to your `NSTextView`.
4. Add an outlet to your `NSWindowController` or `NSDocument` subclass of type ASKSyntaxViewController and connect it to your nib's Syntax View Controller.
5. In code, you can set some or all of the following on the Syntax View Controller:
a. Set the `syntax` property to an `ASKSyntax` object to enable syntax highlighting.
b. Set the `maintainIndentation` property to control auto-indentation.
c. Set the `indentsWithSpaces` property to determine whether pressing the Tab key inserts a tab character or several space characters.
d. Set the `tabDepth` property to determine how many spaces deep a tab character should indent your code, and how many spaces should be inserted when you hit Tab if `indentsWithSpaces` is set.
e. Set the `wrapsLines` property to decide whether or not lines should be wrapped. If they are wrapped, continued lines will be indented four spaces deeper than the first line.
f. Set the `showsLineNumbers` property to determine if a line number gutter will be shown alongside your text view.
6. Optionally, hook up the various ASKSyntaxViewController actions to menu items. This may require you to implement `-supplementalTargetForAction:sender:` in your `NSWindowController` to route these methods to it. These actions are compatible with Cocoa Bindings, so you can use `-bind:toObject:withKeyPath:options:` to bind the `maintainIndentation`, `indentsWithSpaces`, `tabDepth`, `wrapsLines`, and `showsLineNumbers` properties.
7. Load source code into the text view, either by setting the contents of its text storage or by binding the NSTextView.
8. If desired, set the Syntax View Controller's delegate. The Syntax View Controller will set itself to be the NSTextView's delegate, but it will pass all NSTextViewDelegate messages through to its own delegate. It also implements its own delegate methods in ASKSyntaxViewControllerDelegate.

To Do
-----

The current version of SyntaxKit is basically functional, and is used in [Ingist][ingist] for code editing. However, many things are broken or suboptimal:

* There are some rendering glitches in ASKLineNumberView, usually brought out by scrolling.
* -[ASKSyntaxViewController indentSelection:] and -[ASKSyntaxViewController unindentSelection:] do not fully support ASKSyntaxViewController's indentation-controlling properties.
* ASKSyntax(syntaxForType) does not have any mechanism for loading syntaxes shipped in an app or in a user directory, and the mapping between UTIs and syntaxes is kind of hacky.
* ASKSyntax should probably be refactored into components for labeling syntax and for coloring based on those labels. It may make sense to turn the syntax defintion into a set of objects, too.
* I might rework the syntax coloring to base it on regexes.
* SyntaxKit desperately needs more syntaxes. Currently it only supports HTML, CSS, and Objective-C; it uses the Objective-C syntax highlighting for other C variants.

Although this version is labeled as 1.0, I don't expect the API to remain especially stable, particularly around ASKSyntax. Be careful.

Branches
-------

The SyntaxKit git repository includes the following branches:

* `1.x`: This is a stable release version of SyntaxKit with a broadly 1.0-like API.
* `1.x-develop`: This branch includes additional features and bug fixes that will be integrated into the next release of SyntaxKit. These changes are basically complete, but may not be totally ready to go.

It may also include some branches like the following, although these are usually deleted when finished:

* `feature/whatever`: These feature branches are for features that are currently being developed. They are usually *not* finished.
* `release/1.n`: These release branches include final preparations for a future version of SyntaxKit.

If this sort of thing doesn't look familiar to you, you may want to look into [git-flow][gitflow]. (Here, `1.x` is the "master" branch and `1.x-develop` is the "develop" branch.)

Versioning
--------

Like all frameworks, this one has two version numbers:

* `CFBundleShortVersionString` is the "API version" of the library. The first digit is for very large changes that would probably require apps using SyntaxKit to substantially rework their interactions with the library. The second digit is for changes that might require a little bit of work to integrate. The third digit (if present) is for small patches with no serious impact on the functioning of apps using SyntaxKit.
* `CFBundleVersion` is a build number. It should increase over time, and although it follows a particular format ([nnn]n.nn.n), there's no real meaning to the placement of the decimal points; build 1.23.9 will be followed by build 1.24.0. When merging two branches, you should choose the higher build number, and the build number should always increase at least once on a branch. (On my own Mac, the build number is literally incremented every time the project is built, but you don't have to do that.)

Tests
----

The test suite is empty. I wouldn't mind fixing that.

CocoaPod
-------

There isn't one yet. Submit a pull request and I'll likely accept it.

License
------

Because SyntaxKit is assembled from different sources, different parts are under different licenses. **All of these licenses permit commercial distribution of binaries without requiring payment or credit**, and none of them require your changes to be released as open source, so if you are simply using SyntaxKit in an app you have nothing to worry about.

Portions of the code that are original to SyntaxKit are distributed under the MIT license:

> Copyright (c) 2013 Architechies.
>
> Permission is hereby granted, free of charge, to any person obtaining a copy
> of this software and associated documentation files (the "Software"), to deal
> in the Software without restriction, including without limitation the rights
> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
> copies of the Software, and to permit persons to whom the Software is
> furnished to do so, subject to the following conditions:
>
> The above copyright notice and this permission notice shall be included in
> all copies or substantial portions of the Software.
>
> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
> THE SOFTWARE.
`NoodleLineNumberView`, the basis for `ASKLineNumberView`, is also MIT licensed, but is copyrighted 2008-2012 Noodlesoft, LLC.

`UKSyntaxColoredTextViewController`, the basis for `ASKSyntaxViewController` and `ASKSyntax`, is covered by the zlib license, which requires credit be given to Uli Kusterer in all source code distributions of those files.

In general, consult the comments at the top of each file to see how that file is licensed; if you don't see a comment, you may assume it's SyntaxKit code carrying the MIT license.

[uksyntax]: https://github.com/uliwitness/UKSyntaxColoredTextDocument
[noodleline]: http://www.noodlesoft.com/blog/2008/10/05/displaying-line-numbers-with-nstextview/
[ingist]: https://itunes.apple.com/us/app/ingist/id680035328?mt=12
[gitflow]: http://nvie.com/git-model/

2 changes: 2 additions & 0 deletions SyntaxKit.xcodeproj/project.pbxproj
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@
/* End PBXContainerItemProxy section */

/* Begin PBXFileReference section */
8421688817A8D798007FAEAB /* README.md */ = {isa = PBXFileReference; lastKnownFileType = text; path = README.md; sourceTree = "<group>"; };
842931B817A0F0FD00A55E7C /* NSTextView+SyntaxKit.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "NSTextView+SyntaxKit.h"; sourceTree = "<group>"; };
842931B917A0F0FD00A55E7C /* NSTextView+SyntaxKit.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = "NSTextView+SyntaxKit.m"; sourceTree = "<group>"; };
842931BC17A1446E00A55E7C /* ASKSyntax.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = ASKSyntax.h; sourceTree = "<group>"; };
Expand Down Expand Up @@ -133,6 +134,7 @@
8481137C17A0C5FE008C5A6F = {
isa = PBXGroup;
children = (
8421688817A8D798007FAEAB /* README.md */,
8481138F17A0C5FE008C5A6F /* SyntaxKit */,
848113A417A0C5FE008C5A6F /* SyntaxKitTests */,
8481138817A0C5FE008C5A6F /* Frameworks */,
Expand Down
24 changes: 22 additions & 2 deletions SyntaxKit/ASKSyntax.h
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,28 @@
// ASKSyntax.h
// SyntaxKit
//
// Created by Brent Royal-Gordon on 7/25/13.
// Copyright (c) 2013 Architechies. All rights reserved.
// Created by Uli Kusterer on 13.03.10.
// UKSyntaxColoredTextViewController Copyright 2010 Uli Kusterer.
// SyntaxKit Copyright (c) 2013 Architechies. All rights reserved.
//
// This software is provided 'as-is', without any express or implied
// warranty. In no event will the authors be held liable for any damages
// arising from the use of this software.
//
// Permission is granted to anyone to use this software for any purpose,
// including commercial applications, and to alter it and redistribute it
// freely, subject to the following restrictions:
//
// 1. The origin of this software must not be misrepresented; you must not
// claim that you wrote the original software. If you use this software
// in a product, an acknowledgment in the product documentation would be
// appreciated but is not required.
//
// 2. Altered source versions must be plainly marked as such, and must not be
// misrepresented as being the original software.
//
// 3. This notice may not be removed or altered from any source
// distribution.
//

#import <Foundation/Foundation.h>
Expand Down
24 changes: 22 additions & 2 deletions SyntaxKit/ASKSyntax.m
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,28 @@
// ASKSyntax.m
// SyntaxKit
//
// Created by Brent Royal-Gordon on 7/25/13.
// Copyright (c) 2013 Architechies. All rights reserved.
// Created by Uli Kusterer on 13.03.10.
// UKSyntaxColoredTextViewController Copyright 2010 Uli Kusterer.
// SyntaxKit Copyright (c) 2013 Architechies. All rights reserved.
//
// This software is provided 'as-is', without any express or implied
// warranty. In no event will the authors be held liable for any damages
// arising from the use of this software.
//
// Permission is granted to anyone to use this software for any purpose,
// including commercial applications, and to alter it and redistribute it
// freely, subject to the following restrictions:
//
// 1. The origin of this software must not be misrepresented; you must not
// claim that you wrote the original software. If you use this software
// in a product, an acknowledgment in the product documentation would be
// appreciated but is not required.
//
// 2. Altered source versions must be plainly marked as such, and must not be
// misrepresented as being the original software.
//
// 3. This notice may not be removed or altered from any source
// distribution.
//

#import "ASKSyntax.h"
Expand Down
22 changes: 21 additions & 1 deletion SyntaxKit/NSTextView+SyntaxKit.h
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,29 @@
// NSTextView+SyntaxKit.h
// SyntaxKit
//
// Created by Brent Royal-Gordon on 7/24/13.
// Created by Uli Kusterer on 13.03.10.
// UKSyntaxColoredTextViewController Copyright 2010 Uli Kusterer.
// Copyright (c) 2013 Architechies. All rights reserved.
//
// This software is provided 'as-is', without any express or implied
// warranty. In no event will the authors be held liable for any damages
// arising from the use of this software.
//
// Permission is granted to anyone to use this software for any purpose,
// including commercial applications, and to alter it and redistribute it
// freely, subject to the following restrictions:
//
// 1. The origin of this software must not be misrepresented; you must not
// claim that you wrote the original software. If you use this software
// in a product, an acknowledgment in the product documentation would be
// appreciated but is not required.
//
// 2. Altered source versions must be plainly marked as such, and must not be
// misrepresented as being the original software.
//
// 3. This notice may not be removed or altered from any source
// distribution.
//

#import <Cocoa/Cocoa.h>

Expand Down
22 changes: 21 additions & 1 deletion SyntaxKit/NSTextView+SyntaxKit.m
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,29 @@
// NSTextView+SyntaxKit.m
// SyntaxKit
//
// Created by Brent Royal-Gordon on 7/24/13.
// Created by Uli Kusterer on 13.03.10.
// UKSyntaxColoredTextViewController Copyright 2010 Uli Kusterer.
// Copyright (c) 2013 Architechies. All rights reserved.
//
// This software is provided 'as-is', without any express or implied
// warranty. In no event will the authors be held liable for any damages
// arising from the use of this software.
//
// Permission is granted to anyone to use this software for any purpose,
// including commercial applications, and to alter it and redistribute it
// freely, subject to the following restrictions:
//
// 1. The origin of this software must not be misrepresented; you must not
// claim that you wrote the original software. If you use this software
// in a product, an acknowledgment in the product documentation would be
// appreciated but is not required.
//
// 2. Altered source versions must be plainly marked as such, and must not be
// misrepresented as being the original software.
//
// 3. This notice may not be removed or altered from any source
// distribution.
//

#import "NSTextView+SyntaxKit.h"

Expand Down
4 changes: 2 additions & 2 deletions SyntaxKit/SyntaxKit-Info.plist
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@
<key>CFBundlePackageType</key>
<string>FMWK</string>
<key>CFBundleShortVersionString</key>
<string>1.0</string>
<string>1.0.1</string>
<key>CFBundleSignature</key>
<string>????</string>
<key>CFBundleVersion</key>
<string>0.29.8</string>
<string>0.30.1</string>
<key>NSHumanReadableCopyright</key>
<string>Copyright © 2013 Architechies. All rights reserved.</string>
<key>NSPrincipalClass</key>
Expand Down
2 changes: 1 addition & 1 deletion SyntaxKitTests/SyntaxKitTests-Info.plist
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,6 @@
<key>CFBundleSignature</key>
<string>????</string>
<key>CFBundleVersion</key>
<string>0.29.8</string>
<string>0.30.1</string>
</dict>
</plist>

0 comments on commit c1ead1b

Please sign in to comment.