├── LICENSE ├── README.md └── _config.yml /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 OraOpenSource 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Atom packages for Oracle Developers 2 | 3 | [Atom](https://atom.io/) is a free open source powerful text editor. One of its greatest features is the ability to add packages to enhance its functionality. This document covers recommended packages for Oracle developers that use Atom. 4 | 5 | - [Editor enhancements](#editor-enhancements) 6 | - [Project management](#project-management) 7 | - [Minimap](#minimap) 8 | - [File icons](#file-icons) 9 | - [Git](#git) 10 | - [Editing remote files](#editing-remote-files) 11 | - [Terminal emulator](#terminal-emulator) 12 | - [Development enhancements](#development-enhancements) 13 | - [Oracle syntax highlighting](#oracle-syntax-highlighting) 14 | - [Symbols navigation](#symbols-navigation) 15 | - [Source code alignment](#source-code-alignment) 16 | - [Oracle compilation](#oracle-compilation) 17 | - [Script runner](#script-runner) 18 | - [Pigments](#pigments) 19 | - [Colour picker](#colour-picker) 20 | 21 | ## Editor enhancements 22 | 23 | ### Project management 24 | 25 | To quickly navigate around your projects, you can install the extension [`project-manager`](https://atom.io/packages/project-manager). 26 | 27 | It allows you to set up a configuration of your active projects so that you can quickly switch between them. The configuration for this is a `cson` file located in your atom user directory - `$HOME/.atom/projects.cson` most typically. You can quickly access it by opening the command palette (`ctrl+shift+p`) and searching for `Edit projects`. 28 | 29 | ![](https://cloud.githubusercontent.com/assets/1747643/11432340/58a546b2-9500-11e5-8026-d44fa9b0c798.png) 30 | 31 | Then, for each project you define properties such as `title`, `paths`, `icon` and `settings` - there are others, which you can read about on the packages README. 32 | 33 | To get your project added without manually filling out the properties, you can search for `Save Project` in the command palette and it will prompt you for the name of the project, which adds the entries for `title` and `paths` in the project configuration file. 34 | 35 | So for example, I have one project set up for my Atom user directory, as: 36 | 37 | ```cson 38 | atomConfig: 39 | title: "Atom user directory" 40 | paths: [ 41 | "/home/trent/.atom" 42 | ] 43 | icon: "icon-tools" 44 | settings: 45 | "*": 46 | "editor.tabLength": 2 47 | ``` 48 | 49 | This means I can quickly open this project by hitting `alt+shift+P` and searching for `atom user directory`. 50 | 51 | ![](https://cloud.githubusercontent.com/assets/1747643/11432417/1d6b2cd6-9502-11e5-84a1-cd0137508814.png) 52 | 53 | #### Settings 54 | 55 | Any settings you can apply system wide, you can also apply in the project configuration, with `*` being the wild card for all file types. You could alternatively have specific settings for specific language scopes. For instance, in the documentation, it has the example: 56 | 57 | ```cson 58 | '.source.coffee': 59 | 'editor.tabLength': 2 60 | 'editor.preferredLineLength': 80 61 | ``` 62 | 63 | If you look at the grammar [specification](https://github.com/atom/language-coffee-script/blob/master/grammars/coffeescript.cson) for CoffeeScript, you will see it's defined the `scopeName` as `source.coffee` which is why the above setting is mapped to `.source.coffee`. 64 | 65 | #### Icon 66 | 67 | The icons you can use against your projects are based on [GitHub Octicons](https://octicons.github.com/). For example, on the Atom user directory project I set up earlier, I specified the icon as `icon-tools`. If you look at the grid of icons, you will find that particular icon towards the bottom. 68 | 69 | Clicking onto will give you the class name as `octicon-tools`. So in our project settings, we use that same class name, only replacing `octicon` with `icon` - thus becoming `icon-tools`. 70 | 71 | 72 | ![](https://cloud.githubusercontent.com/assets/1747643/11433288/1e8bdaea-950f-11e5-9fec-de144f7ba02a.png) 73 | 74 | ### Minimap 75 | 76 | The extension [`minimap`](https://atom.io/packages/minimap) gives a zoomed out view of the code, on either the left or right hand side of the file that you can drag to scroll to a specific portion of the code. 77 | 78 | ![](https://cloud.githubusercontent.com/assets/1747643/11354495/f057cc2c-929f-11e5-8d31-d7252f001ec9.png) 79 | 80 | ### File icons 81 | 82 | The extensions [`file-icons`](https://atom.io/packages/file-icons) adds icons specific to a files extension - just to add a bit of eye candy, and one more visual recognition of the file type. The icons are based on FontAwesome (and derivative(s)) fonts. 83 | 84 | As a little example, before using this package: 85 | 86 | ![](https://cloud.githubusercontent.com/assets/1747643/11354338/d6529614-929e-11e5-9bb9-b7325e5aaaf2.png) 87 | 88 | and after: 89 | 90 | ![](https://cloud.githubusercontent.com/assets/1747643/11354347/e8358f62-929e-11e5-832c-a4b085ec07b6.png) 91 | 92 | note: The icon on `foo.pks` in the screenshot above hasn't yet made it into the package - but gives an idea of what is possible 93 | 94 | ### Git 95 | 96 | If you would like to be able to perform git operations directly from your editor, you want the extension [`git-plus`](https://atom.io/packages/git-plus). This extension adds commands into the command palette and through context menu's so that you can quickly perform git-operations straight out of your editor. 97 | 98 | For example, From the command pallette, you can run: 99 | 100 | * `Git Plus: Add` to add the active file 101 | * `Git Plus: Add and Commit` to add the active file and trigger a commit 102 | * `Git Plus: Commit` to commit all staged files 103 | 104 | And many more. 105 | 106 | ![image](https://cloud.githubusercontent.com/assets/1747643/25365292/0c2ee112-29ab-11e7-8085-a4953d3f9513.png) 107 | 108 | If you are more of a point-and-click type of person, you can access these commands by right clicking a file in the tree. There will be a menu entry for Git Plus where you can access a sub-set of available commands. 109 | 110 | ![image](https://cloud.githubusercontent.com/assets/1747643/25365325/4eeb4374-29ab-11e7-9732-b7de7146ee52.png) 111 | 112 | ### Editing remote files 113 | 114 | The extension [`remote-edit`](https://atom.io/packages/remote-edit) allows editing of files from ftp/sftp. 115 | 116 | To set up a new host, open the command palette and search for `remote edit: new host Sftp` 117 | 118 | ![image](https://cloud.githubusercontent.com/assets/1747643/25269002/37fa98a8-26be-11e7-9490-29a5788e9baf.png) 119 | 120 | ![image](https://cloud.githubusercontent.com/assets/1747643/25268955/091d142a-26be-11e7-9a56-a9c68861095b.png) 121 | 122 | This configuration gets serialised into the default config: `~/.atom/remoteEdit.json` (can be changed through settings) 123 | 124 | Once that is set up, you can open those files by opening the `remote-edit` browse dialog - accessed by the command `Remote edit: Browse`. This will bring up a list of saved hosts that you can then browse. 125 | 126 | ![image](https://cloud.githubusercontent.com/assets/1747643/25269394/c88c5da6-26bf-11e7-8562-3d92031880e4.png) 127 | 128 | ![image](https://cloud.githubusercontent.com/assets/1747643/25269419/e55a3142-26bf-11e7-84b2-956f6d96d435.png) 129 | 130 | One minor issue that I noticed, is that it doesn't show hidden files - and typing them in manually also doesn't load the file. 131 | 132 | ### Terminal emulator 133 | 134 | A common requirement for developers is to be able to access a terminal from within the editor. Whilst there are a number of packages that come with one implementation or another, in my testing I found [`platformio-ide-terminal`](https://atom.io/packages/platformio-ide-terminal) to work best (another popular one being `terminal-plus`, but unfortunately didn't seem to be working on my Linux based system). 135 | 136 | Once installed, you will see a `+` and `x` symbol in the bottom left hand side of your status bar. Clicking on the `+` will open up a new console (you can have more than one). 137 | 138 | ![image](https://cloud.githubusercontent.com/assets/1747643/25366732/f2d61be0-29b4-11e7-9f82-f808a0445699.png) 139 | 140 | ![image](https://cloud.githubusercontent.com/assets/1747643/25366745/08e253f4-29b5-11e7-8827-fad01904e01e.png) 141 | 142 | One "feature" that I found was that when running `git status`, then changes would come in with a drop shadow which made it difficult to read. 143 | 144 | ![image](https://cloud.githubusercontent.com/assets/1747643/25366792/5e64136c-29b5-11e7-9b89-f3841b24be42.png) 145 | 146 | To get around this, I added the following to my user stylesheet: 147 | 148 | ```css 149 | //adapted from: https://github.com/jeremyramin/terminal-plus/issues/124 150 | .platformio-ide-terminal.terminal-view .xterm > .terminal { 151 | text-shadow: none; 152 | } 153 | ``` 154 | 155 | After this change, it comes through more readable as: 156 | 157 | ![image](https://cloud.githubusercontent.com/assets/1747643/25366809/832f5cf6-29b5-11e7-86e6-12d7752cfa02.png) 158 | 159 | ## Development enhancements 160 | 161 | ### Oracle syntax highlighting 162 | 163 | Syntax highlighting for Oracle (PL/SQL) based code files is made available through the extension [`language-oracle`](https://atom.io/packages/language-oracle). 164 | 165 | Once installed, the language will automatically pickup the grammar when opening files with all the common PL/SQL file extensions. If you have not yet saved your file, or are using a currently un-recognised file extension, you can manually apply the language with the keyboard shortcut `ctrl+shft+L` and searching for PL/SQL 166 | 167 | ![](https://cloud.githubusercontent.com/assets/1747643/11353907/74f00ca6-929b-11e5-89f1-4a52dca44787.png) 168 | 169 | ### Symbols navigation 170 | 171 | The extension to add a tree of your source code for quick navigation is provided through the extension [`symbols-tree-view`](https://atom.io/packages/symbols-tree-view). 172 | 173 | This package provides a symbols/class view on the right hand side of your text editor. Clicking on any symbol will take you to that position in the code. 174 | 175 | ![](https://cloud.githubusercontent.com/assets/1747643/11354004/62272df6-929c-11e5-89a4-adc802e6349c.png) 176 | 177 | The pane get easily be toggled on and off with the keyboard shortcut `ctrl+alt+o`. 178 | 179 | ### Source code alignment 180 | 181 | Some developers prefer assignment operators in a given block to be aligned over multiple lines so that all assignment values begin at the same point. If you are one of those people, the extension [`atom-alignment`](https://atom.io/packages/atom-alignment) solves that by allowing you to highlight a section of code, and applying the alignment. 182 | 183 | The key bindings are `ctrl+alt+A` or `ctrl+cmd+A`. Best demonstrated with an example. So first you need to highlight any text where assignment operators occur, then run the aforementioned key bindings (or by selecting from the menu option, `Packages->atom-alignment`). 184 | 185 | Example 1: Just the package call 186 | 187 | Before: 188 | 189 | ```plsql 190 | declare 191 | l_short_field NUMBER; 192 | l_really_really_long_field NUMBER; 193 | begin 194 | 195 | l_short_field := 1; 196 | l_really_really_long_field := 999; 197 | 198 | field_updater.get_ready_for_update; 199 | 200 | field_updater.update_details( 201 | l_short_field => l_short_field 202 | , l_really_really_long_field => l_really_really_long_field 203 | ); 204 | 205 | end; 206 | / 207 | ``` 208 | 209 | After: 210 | 211 | ```plsql 212 | declare 213 | l_short_field NUMBER; 214 | l_really_really_long_field NUMBER; 215 | begin 216 | 217 | l_short_field := 1; 218 | l_really_really_long_field := 999; 219 | 220 | field_updater.get_ready_for_update; 221 | 222 | field_updater.update_details( 223 | l_short_field => l_short_field 224 | , l_really_really_long_field => l_really_really_long_field 225 | ); 226 | 227 | end; 228 | / 229 | ``` 230 | 231 | Example 2: The whole package 232 | 233 | ```plsql 234 | declare 235 | l_short_field NUMBER; 236 | l_really_really_long_field NUMBER; 237 | begin 238 | 239 | l_short_field := 1; 240 | l_really_really_long_field := 999; 241 | 242 | field_updater.get_ready_for_update; 243 | 244 | field_updater.update_details( 245 | l_short_field => l_short_field 246 | , l_really_really_long_field => l_really_really_long_field 247 | ); 248 | 249 | end; 250 | / 251 | ``` 252 | 253 | After: 254 | 255 | ``` 256 | declare 257 | l_short_field NUMBER; 258 | l_really_really_long_field NUMBER; 259 | begin 260 | 261 | l_short_field := 1; 262 | l_really_really_long_field := 999; 263 | 264 | field_updater.get_ready_for_update; 265 | 266 | field_updater.update_details( 267 | l_short_field => l_short_field 268 | , l_really_really_long_field => l_really_really_long_field 269 | ); 270 | 271 | end; 272 | / 273 | ``` 274 | 275 | One change I did make, was to clear one of the settings `Add Space Postfix`. 276 | 277 | ![](https://cloud.githubusercontent.com/assets/1747643/11433471/c894e9da-9511-11e5-94e0-35e06826319d.png) 278 | 279 | If that is left enabled, the previous block would have come out as: 280 | 281 | ```plsql 282 | declare 283 | l_short_field NUMBER; 284 | l_really_really_long_field NUMBER; 285 | begin 286 | 287 | l_short_field := 1; 288 | l_really_really_long_field := 999; 289 | 290 | field_updater.get_ready_for_update; 291 | 292 | field_updater.update_details( 293 | l_short_field = > l_short_field 294 | , l_really_really_long_field = > l_really_really_long_field 295 | ); 296 | 297 | end; 298 | / 299 | ``` 300 | 301 | ### Oracle compilation 302 | 303 | The extension [`build-oracle`](https://github.com/tschf/atom-build-oracle) allows you to compile your Oracle scripts against the database. It does this be expanding on the `build` package, which is a generic extension for building on a variety of languages/platforms. 304 | 305 | After you install, to start building against your database you need to set up a configuration (json) file, named `.atom-build-oracle.json`. The first time you add the configuration, you will need to reload Atom for the build targets to be recognised. This configuration expects an array of objects with two fields: `targetName` and `connectString`. 306 | 307 | For example, if I want two build targets against the `hr` schema, my configuration file will look like: 308 | 309 | ``` 310 | [ 311 | { 312 | "targetName" : "HR_DEV", 313 | "connectString" : "hr/hr@ORCLDEV" 314 | }, 315 | { 316 | "targetName" : "HR_PRD", 317 | "connectString" : "hr/hr@ORCLPRD" 318 | } 319 | ] 320 | ``` 321 | 322 | With this applied, in the bottom left corner of your screen (in the status bar), you will see the build target of the first one defined in the config. Clicking on that will then bring up a list of targets at the top of the screen that you can click on to compile the active file against that connection. 323 | 324 | ![image](https://cloud.githubusercontent.com/assets/1747643/24751026/6d917fcc-1b0b-11e7-9342-0a5a114a8753.png) 325 | 326 | ![image](https://cloud.githubusercontent.com/assets/1747643/24751041/7df321cc-1b0b-11e7-92d6-34da10a7c185.png) 327 | 328 | Alternatively, you can hit the (default) key binding `ctrl+alt+b` to compile against the active build target. 329 | 330 | This project depends on SQL*Plus (or SQLcl), so for further set up instructions, it is worth reviewing the [README](https://github.com/tschf/atom-build-oracle/blob/master/README.md) of the project - for SQLcl, it is just a matter of going in the plugin settings and setting it to use sqlcl instead of the default sqlplus. 331 | 332 | ### Script runner 333 | 334 | Unlike `build-oracle`, or more succintly, `build`, which typically depends on a build file, the extension [`script`](https://atom.io/packages/script) allows you to run the file based on the extension and has support for large number of languages. The keyboard shortcut to run a script defaults to `ctrl+shift+b`. 335 | 336 | Suppose you have a JavaScript file you want to quickly run to test out, hit the keyboard shortcut and a little panel at the bottom of the page will show the output/results. 337 | 338 | ![image](https://cloud.githubusercontent.com/assets/1747643/24910474/43459902-1f0b-11e7-8338-1e71a3482515.png) 339 | 340 | ### Pigments 341 | 342 | The extension [`pigments`](https://atom.io/packages/pigments) will highlight colours in your source code. This can be helpful when using for example hex colour codes, or rgb values, to know what colour is actually being applied. 343 | 344 | When dealing with CSS pre-processor's such as less, and colour variables that have been declared will come through in the palette. To show the colours, run the command `show palette`. 345 | 346 | ![image](https://cloud.githubusercontent.com/assets/1747643/24865237/021c0cac-1e4a-11e7-9c23-0f9e80c01b18.png) 347 | 348 | If I have defined a colour as: `@my-var: #123456;` in my `less` file, the palette will show the following: 349 | 350 | ![image](https://cloud.githubusercontent.com/assets/1747643/24865492/c77bbb50-1e4a-11e7-91ff-35824a047869.png) 351 | 352 | Pigments also comes with a command to list all colours defind in the project. Run the command `Find colors`. 353 | 354 | ![image](https://cloud.githubusercontent.com/assets/1747643/24865564/fa69a0fe-1e4a-11e7-8d68-dc091ad46724.png) 355 | 356 | 357 | ### Colour picker 358 | 359 | The extensions [`color-picker`](https://atom.io/packages/color-picker) allows you to use a UI to choose a colour you want. There is a default trigger binding of `ctrl+alt+c`. So if you mouse over a colour code in your source file and hit the trigger key, the colour picker will present itself. 360 | 361 | ![image](https://cloud.githubusercontent.com/assets/1747643/25313111/48312bf2-286b-11e7-8d5e-648a49fe151f.png) 362 | 363 | Clicking the big button at the top that displays the colour and also the HEX (or other desired format) code, will either insert or replace the colour value in your source file. 364 | 365 | One issue, it won't work with colour names, such as `red`, `green`, `blue`, etc. 366 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-cayman 2 | --------------------------------------------------------------------------------