crocon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b7a9f4c23fc72ce034224faa7f2dfe3b4f9fd947
+  data.tar.gz: abcbd12171cf812369df816988926a6e3ffb4a31
+SHA512:
+  metadata.gz: 44ed9441c980993347cdf7a3d3ede8dbe6a172ecb54feb3c6d277a5682ae3dd7706968cb04c9beee619a2a1ed6de1f11e63ccd39ae534f1ecef7da10fee14011
+  data.tar.gz: 159925da2a917cfd1438603300aed24e8df1dd4534613ee84ce8821fa4042fb4e869875f4d16769e79271cdfebe57eb8d2d07a2118c8ff6e5bf90f58ab873f85

data/README.md

@@ -0,0 +1,283 @@
+# Crocon 🐊
+
+**Crocon makes developer console great again.**
+
+Crocon is a Javascript wrapper for browser's developer console. Its goal is to make debugging
+painless, convenient and beautiful.
+
+This is a Rails gem version of the library. For source files and an npm package, go [here](https://github.com/akxcv/crocon).
+
+## Installation
+
+Add this to your `Gemfile`:
+```
+gem 'crocon'
+```
+
+Add this to your `application.js`:
+```
+//= require crocon
+```
+
+Add this to your `application.css`:
+```
+*= require crocon
+```
+
+## Why?
+
+The builtin developer console in modern browsers suffers from a number of problems. Here are some
+of the big ones:
+
+**There's no good way to turn logging on/off.**
+
+Most of the time you don't want your clients to
+see debugging output in their console on your production website. But, `console.log` does not
+care if it runs in development or production, it's going to log anyway. This leads to developers
+seldom using the console *or* writing `console.log` over and over again just to erase
+it afterwards (...just to write it back again afterwards, and so on). Disabling the console
+is still possible (e.x. `if (!debug) console.log = function () {}`), but it's not a good solution
+if you use other console methods (which you should!). Also, imagine you want to be able to
+see debugging output in production while normal website users don't see anything. What do you do?
+
+Crocon solves this problem by introducing a flexible enable/disable mechanism. First of all, you
+can enable or disable it during initialization: `crocon = new Crocon({ enabled: debug })`
+(assuming that `debug` is `true` in development and `false` in production). But also, you can
+enable or disable Crocon in your browser (`crocon.enable()` or `crocon.disable()`), which will
+override the global `enabled` option. Thus, you can easily switch Crocon on/off in any environment,
+and it will only affect *your* console.
+
+See [initialization options](#initialization-options).
+
+**`console.group` is a great idea, but it's not implemented well**
+
+With [`console.group`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#group) you can split your output in foldable groups, which is a *very* good thing
+to be able to do. However, a lot of JS these days is *asynchronous*, which is something you have
+to constantly think about if you want to group your output.
+
+Consider this simple scenario:
+
+```js
+async function f1() {
+    console.group('group 1');
+    console.log('function 1 start');
+    await sleep(1000);
+    console.log('function 1 end');
+    console.groupEnd();
+}
+
+async function f2() {
+    console.group('group 2');
+    console.log('function 2 start');
+    await sleep(500);
+    console.log('function 2 end');
+    console.groupEnd();
+}
+
+f1(); f2()
+```
+
+Result:
+
+![Async and groups](/images/async_console_groups.png?raw=true)
+
+Crocon solves this by creating a different implementation of groups. With Crocon, you can use
+groups like this:
+
+```js
+crocon.group('my namespace').log('hello from my namespace')
+/* or */
+crocon.group('my namespace', function () {
+  crocon.log('hello from my namespace')
+  /* ... */
+})
+```
+
+See [grouping](#grouping)
+
+**`console.log` supports formatting with CSS, but it's not convenient**
+
+`console` supports formatting with CSS rules:
+
+```js
+console.log('roses are %cred%c, violets are %cblue', 'color: red;', 'color: black;', 'color: blue;')
+```
+
+Result:
+
+![Console formatting](/images/console_formatting.png?raw=true)
+
+This is awesome, but really not convenient.
+
+Crocon makes formatting much easier by introducing a markdown-like syntax. See [formatting](#formatting).
+
+## Browser support
+
+TBD
+
+## Usage
+
+Methods that work exactly like their console's counterparts:
+
+- [`assert`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#assert)
+- [`count`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#count)
+- [`debug`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#consoledebugobject_object)
+[also supports formatting](#formatting)
+- [`dir`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#dir)
+- [`dirxml`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#consoledirxmlobject)
+- [`error`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#error)
+[also supports formatting](#formatting), see [known issues](#known-issues)
+- [`info`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#consoleinfoobject_object) [also supports formatting](#formatting)
+- [`log`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#log)
+[also supports formatting](#formatting)
+- [`timeStamp`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#timestamp)
+- [`trace`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#trace)
+see [known issues](#known-issues)
+- [`warn`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#warn)
+[also supports formatting](#formatting)
+
+Also:
+
+- [`profile` and `profileEnd`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#profile)
+as well as
+[`time` and `timeEnd`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#time)
+support lambda syntax:
+
+```js
+crocon.profile('profile1')
+myVar = myFunction()
+crocon.profileEnd()
+
+/* is the same as */
+
+myVar = crocon.profile('profile1', myFunction)
+```
+
+- `group` is described in [grouping](#grouping).
+
+### Initialization options
+
+```js
+crocon = new Crocon({
+  enabled: true,
+  enableFormatting: true,
+  collapseGroups: false,
+  modifyConsole: true
+})
+```
+- `enabledByDefault`: Defines whether to enable or disable Crocon.
+When Crocon is disabled, it will not produce any output. However, lambda versions of `profile`, `time` and `group` will still execute given functions. Default: `true`.
+- `enableFormatting`: Defines whether [formatting](#formatting) should be enabled. Default: `true`.
+- `collapseGroups`: Defines whether [groups](#grouping) should be
+collapsed or not. Default: `false` (expanded).
+- `modifyConsole`: Defines whether Crocon needs to modify `console` upon initialization.
+Generally, modifying global objects is a bad thing to do, but this is required if you want Crocon to
+handle console output correctly. Crocon is modifying `console` functions *very carefully* (it just
+needs to hook to those methods). You can safely disable this options, but regular console output
+will occasionally get stuck inside groups it does not belong to. see [known issues](#known-issues). Default: `true`.
+
+### Grouping
+
+Groups in Crocon work a little different from console's groups. There are two ways to group the output.
+
+```js
+/* method 1 */
+crocon.group('group one').log('inside group 1')
+
+/* method 2 */
+crocon.group('group one', function () {
+  crocon.log('inside group 1')
+})
+```
+
+You can easily mix methods together and nest groups however you want:
+
+```js
+crocon.group('user login', function () {
+  crocon.info('user login started')
+  crocon.group('credentials').log('credentials are [correct].green')
+  /* code */
+  crocon.info('[success].badge.green')
+})
+
+crocon.group('group 1').log('some more output')
+crocon.group('group 1', 'another group!').log('still nested correctly')
+```
+
+Output:
+
+![Group output](/images/group_output.png?raw=true)
+
+When `document` is not in focus (e.g. your console is in focus), the output becomes:
+
+![Inline group output](/images/inline_group_output.png?raw=true)
+
+This behaviour is explained in [known issues](#known-issues).
+
+### Formatting
+
+Crocon supports Markdown-like string formatting. Here's the options:
+- `**bold**`
+- `*italic*`
+- `~strikethrough~`
+- `_underline_`
+- `[custom text].classOne.classTwo...`. This syntax allows you to apply CSS classes to text in
+square brackets. Available classes are: `badge`, `bold`, `italic`, `strikethrough`, `underline` and [color classes](#color-classes).
+
+At the moment, you cannot nest formatting options into each other.
+Objects and functions are not formattable, but they likely will be in the future.
+
+#### Color classes
+
+Crocon supports following color classes (both for badges and normal text):
+- `.blue`
+- `.orange`
+- `.red`
+- `.green`
+- `.cyan`
+- `.purple`
+
+#### Adding custom / overriding existing styles
+
+All styles are declared in a stylesheet and thus are easily extensible.
+See [`index.scss`](index.scss).
+At the moment, only these attributes are supported: `margin`, `color`, `background-color`,
+`border-radius`, `padding`, `font-weight`, `font-style`, `text-decoration`.
+
+## Known issues
+
+- **There's no way to detect when console output happens**. Development tools are separate from `window` and `document`,
+and there is no way to know if the output is happening. We can detect things like `console.log`
+by modifying those functions (hence the `modifyConsole` init parameter), but we cannot know when,
+say, an error thrown with `throw` is going to appear in console. Groups are implemented in such a way that they don't get closed
+until it's necessary, so that leads to console output being stuck inside groups it doesn't belong to.
+Part of the problem is solved by modifying `console`, but another part is not solvable without a browser extension.
+The best we can do is to detect whether or not `document` is in focus (with `document.hasFocus()`).
+This enables us to change how groups work if `document` is not in focus (say, `console` is in focus).
+However, some things (like `throw` or click on the "clear console" button) are simply not catchable.
+So, **some output will inevitably get stuck in a group it doesn't belong**. Beware of this, especially when using `collapseGroups = true`.
+
+- **Stack traces from `crocon.error` and `crocon.trace` contain unneeded information**.
+Since `crocon.error` and `crocon.trace` call some functions under the hood, the stack trace produced
+by those functions will contain several unneeded calls.
+
+*All of this is according to the author's research. If you know a solution to this problem, you're
+highly encouraged to open an issue and/or a pull request at [akxcv/crocon](https://github.com/akxcv/crocon).*
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/akxcv/crocon.
+
+## License
+
+The package is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+## TODO
+
+- Support nested styles
+- Log history
+- Replace stylesheet with in-memory CSS?
+- Focus mode (see only the logs you need **right now**)
+- Custom styles in formatting (e.x. `[my text]{color: #434433;}`)
+- Browser support
+- Object and function formatting

data/lib/crocon.rb

@@ -0,0 +1,4 @@
+require 'crocon/rails'
+
+module Crocon
+end

data/lib/crocon/rails.rb

@@ -0,0 +1,7 @@
+require "crocon/rails/engine"
+require "crocon/rails/version"
+
+module Crocon
+  module Rails
+  end
+end

data/lib/crocon/rails/engine.rb

@@ -0,0 +1,6 @@
+module Crocon
+  module Rails
+    class Engine < ::Rails::Engine
+    end
+  end
+end

data/lib/crocon/rails/version.rb

@@ -0,0 +1,5 @@
+module Crocon
+  module Rails
+    VERSION = '0.1.0'
+  end
+end

data/vendor/assets/javascripts/crocon.js

@@ -0,0 +1,13 @@
+(function e(t,n,r){function s(o,u){if(!n[o]){if(!t[o]){var a=typeof require=="function"&&require;if(!u&&a)return a(o,!0);if(i)return i(o,!0);var f=new Error("Cannot find module '"+o+"'");throw f.code="MODULE_NOT_FOUND",f}var l=n[o]={exports:{}};t[o][0].call(l.exports,function(e){var n=t[o][1][e];return s(n?n:e)},l,l.exports,e,t,n,r)}return n[o].exports}var i=typeof require=="function"&&require;for(var o=0;o<r.length;o++)s(r[o]);return s})({1:[function(require,module,exports){
+window.Crocon=require("./src/index");
+},{"./src/index":5}],2:[function(require,module,exports){
+var BrowserAdapter={log:console.log,debug:console.debug,info:console.info,warn:console.warn,error:console.error,group:console.group,groupCollapsed:console.groupCollapsed,groupEnd:console.groupEnd,assert:console.assert,count:console.count,dir:console.dir,dirxml:console.dirxml,profile:console.profile,profileEnd:console.profileEnd,time:console.time,timeEnd:console.timeEnd,timeStamp:console.timeStamp,trace:console.trace};module.exports=BrowserAdapter;
+
+},{}],3:[function(require,module,exports){
+var Formatter={format:function(t){var e,r=[],a=[],s=0;for(var o in t){var n=this.formatObject(t[o]);if("undefined"==typeof n||!n[1].length)break;r.push(n[0]),a.push.apply(a,n[1]),s+=1}return t.splice(0,s),e=[],r.length&&(e.push(r.join(" ")),e.push.apply(e,a)),e.push.apply(e,t),e},formatObject:function(t){if("string"==typeof t)return this.formatString(t)},formatString:function(t){for(var e,r=[];this.canFormat(t);){var a=this.getRelevantMatch(t);e="string"==typeof a.format.classes?a.format.classes:a.format.classes(a.match),t=t.replace(a.format.regex,function(t,e){return"%c"+e+"%c"}),r.push(this.computeStyle(e)),r.push(this.computeStyle("default"))}return[t,r]},canFormat:function(t){for(var e in this.formats)if(this.formats[e].regex.test(t))return!0;return!1},getRelevantMatch:function(t){var e=[];for(var r in this.formats){var a=this.formats[r];a.regex.test(t)&&e.push({match:t.match(a.regex),format:a})}return e.sort(function(t,e){return t.match.index-e.match.index})[0]},computeStyle:function(t){var e=document.createElement("div");e.id="crocon",e.className=t,e.style="display: none;",document.getElementsByTagName("body")[0].appendChild(e);var r=getComputedStyle(e),a=[];for(var s in this.supportedStyles){var o=this.supportedStyles[s];a.push(o+":"+r.getPropertyValue(o))}return a.join(";")},supportedStyles:["margin","color","background-color","border-radius","padding","font-weight","font-style","text-decoration"],formats:[{regex:/\*\*([^\*]+)\*\*/,classes:"bold"},{regex:/\*([^\*]+)\*/,classes:"italic"},{regex:/~([^~]+)~/,classes:"strikethrough"},{regex:/_([^_]+)_/,classes:"underline"},{regex:/\[([^\[\]]+)\](\.[\.\w]+)/,classes:function(t){return t[2].split(".").join(" ")}}]};module.exports=Formatter;
+
+},{}],4:[function(require,module,exports){
+var BrowserAdapter=require("./browserAdapter"),GroupManager={currentStack:[],previousStack:[],globalStack:[],bindEvents:function(){var r=this;window.addEventListener("blur",function(){r.clear()})},group:function(r,t,e){if(e?(this.ungroup(!1),this.globalStack.push(t)):this.currentStack=t,document.hasFocus()){var o;if(e)for(o in t)BrowserAdapter[r](t[o]);else{var a=0;for(o in this.currentStack)this.previousStack[o]===this.currentStack[o]&&(a+=1);var n=this.previousStack.length-a;for(o=0;o<n;o++)BrowserAdapter.groupEnd();var c=this.currentStack.slice(a);for(o in c)BrowserAdapter[r](c[o])}}},ungroup:function(r){if(this.previousStack.length&&!this.currentStack.length&&this.previousStack.forEach(function(){BrowserAdapter.groupEnd()}),r){var t=this.globalStack.pop();t.forEach(function(){BrowserAdapter.groupEnd()})}this.previousStack=this.currentStack,this.currentStack=[]},clear:function(){this.previousStack.forEach(function(){BrowserAdapter.groupEnd()}),this.currentStack.forEach(function(){BrowserAdapter.groupEnd()}),this.previousStack=[]}};module.exports=GroupManager;
+},{"./browserAdapter":2}],5:[function(require,module,exports){
+function Crocon(o){var r={enabled:!0,enableFormatting:!0,collapseGroups:!1,modifyConsole:!0};o||(o={});for(var n in r)o.hasOwnProperty(n)||(o[n]=r[n]);if(this.enabled=o.enabled,this.enableFormatting=o.enableFormatting,this.collapseGroups=o.collapseGroups,this.formattableMethods=["log","info","debug","warn","error","focus"],GroupManager.bindEvents(),o.modifyConsole){var e=function(o,r){return GroupManager.clear(),BrowserAdapter[o].apply(BrowserAdapter,r)};console.log=function(){e("log",arguments)},console.debug=function(){e("debug",arguments)},console.info=function(){e("info",arguments)},console.warn=function(){e("warn",arguments)},console.error=function(){e("error",arguments)},console.assert=function(){e("assert",arguments)},console.clear=function(){GroupManager.clear()},console.count=function(){e("count",arguments)},console.dir=function(){e("dir",arguments)},console.dirxml=function(){e("dirxml",arguments)},console.group=function(){e("group",arguments)},console.groupCollapsed=function(){e("groupCollapsed",arguments)},console.groupEnd=function(){e("groupEnd",arguments)},console.profile=function(){e("profile",arguments)},console.profileEnd=function(){e("profileEnd",arguments)},console.time=function(){e("time",arguments)},console.timeEnd=function(){e("timeEnd",arguments)},console.timeStamp=function(){e("timeStamp",arguments)},console.trace=function(){e("trace",arguments)}}}var GroupManager=require("./groupManager"),BrowserAdapter=require("./browserAdapter"),Formatter=require("./formatter");Crocon.prototype={log:function(){this.print("log",[].slice.call(arguments))},debug:function(){this.print("debug",[].slice.call(arguments))},info:function(){this.print("info",[].slice.call(arguments))},warn:function(){this.print("warn",[].slice.call(arguments))},error:function(){this.print("error",[].slice.call(arguments))},assert:function(){this.print("assert",[].slice.call(arguments))},count:function(o){this.print("count",[o])},dir:function(o){this.print("dir",[o])},dirxml:function(o){this.print("dirxml",[o])},profile:function(){var o=[].slice.call(arguments),r=o.pop();if("function"==typeof r){this._isEnabled()&&BrowserAdapter.profile(o[0]);var n=r.call();return this.profileEnd(),n}this._isEnabled()&&BrowserAdapter.profile(o[0])},profileEnd:function(){this._isEnabled()&&BrowserAdapter.profileEnd()},time:function(){var o=[].slice.call(arguments),r=o.pop();if("function"==typeof r){this._isEnabled()&&BrowserAdapter.time(o[0]);var n=r.call();return this.timeEnd(o[0]),n}this._isEnabled()&&BrowserAdapter.time(o[0])},timeEnd:function(o){this._isEnabled()&&BrowserAdapter.timeEnd(o)},timeStamp:function(o){this._isEnabled()&&BrowserAdapter.timeStamp(o)},trace:function(o){this.print("trace",[o])},group:function(){var o=[].slice.call(arguments),r=this.collapseGroups?"groupCollapsed":"group";if("function"==typeof o[o.length-1]){var n=o.pop();this._isEnabled()&&GroupManager.group(r,o,!0);var e=n.call();return this._isEnabled()&&GroupManager.ungroup(!0),e}return this._isEnabled()&&GroupManager.group(r,o),this},print:function(o,r){if(GroupManager.ungroup(),this._isEnabled()){var n=!document.hasFocus()&&GroupManager.previousStack.length+GroupManager.globalStack.length;if(n){var e=[],t=GroupManager.previousStack;t.unshift.apply(t,GroupManager.globalStack.reduce(function(o,r){return o.concat(r)},[])),GroupManager.previousStack=[];for(var i in t)e.push(t[i]);var a=e.join(" -> ")+" :: ";"string"==typeof r[0]?r[0]=a+r[0]:r.unshift(a)}this.formattableMethods.indexOf(o)>-1&&this.enableFormatting&&(r=Formatter.format(r)),n?(BrowserAdapter.groupCollapsed.apply(BrowserAdapter,r),BrowserAdapter.groupEnd()):BrowserAdapter[o].apply(BrowserAdapter,r)}},enable:function(){localStorage&&localStorage.setItem("croconEnabled","true")},disable:function(){localStorage&&localStorage.setItem("croconEnabled","false")},_isEnabled:function(){return localStorage&&localStorage.croconEnabled?"false"!==localStorage.croconEnabled:this.enabled}},module.exports=Crocon;
+},{"./browserAdapter":2,"./formatter":3,"./groupManager":4}]},{},[1]);

data/vendor/assets/stylesheets/crocon.css

@@ -0,0 +1,55 @@
+#crocon {
+  color: black;
+  background-color: transparent;
+  border-radius: 0;
+  padding: 0;
+  margin: 0;
+  font-weight: normal;
+  font-style: normal; }
+  #crocon.badge {
+    color: white;
+    background-color: black;
+    border-radius: 3px;
+    padding: 2px;
+    margin: 0 2px; }
+    #crocon.badge.blue {
+      color: white;
+      background-color: #61afef; }
+    #crocon.badge.orange {
+      color: white;
+      background-color: #d19a66; }
+    #crocon.badge.red {
+      color: white;
+      background-color: #e06c75; }
+    #crocon.badge.green {
+      color: white;
+      background-color: #98c379; }
+    #crocon.badge.cyan {
+      color: white;
+      background-color: #56b6c2; }
+    #crocon.badge.purple {
+      color: white;
+      background-color: #c678dd; }
+    #crocon.badge.focus {
+      color: #bada55;
+      background: #444; }
+  #crocon.blue {
+    color: #4078f2; }
+  #crocon.orange {
+    color: #986801; }
+  #crocon.red {
+    color: #e45649; }
+  #crocon.green {
+    color: #50a14f; }
+  #crocon.cyan {
+    color: #0184bc; }
+  #crocon.purple {
+    color: #a626a4; }
+  #crocon.bold {
+    font-weight: bold; }
+  #crocon.italic {
+    font-style: italic; }
+  #crocon.strikethrough {
+    text-decoration: line-through; }
+  #crocon.underline {
+    text-decoration: underline; }

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: crocon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexander Komarov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-02-11 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  Crocon is a Javascript wrapper for browser's developer console.
+                            Its goal is to make debugging painless, convenient and beautiful.
+email:
+- ak@akxcv.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/crocon.rb
+- lib/crocon/rails.rb
+- lib/crocon/rails/engine.rb
+- lib/crocon/rails/version.rb
+- vendor/assets/javascripts/crocon.js
+- vendor/assets/stylesheets/crocon.css
+homepage: https://github.com/akxcv/crocon
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: Make your console great again
+test_files: []