logalize 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d7aa3313afb986e5ed8fc08864993f69612f0d48
+  data.tar.gz: b509c0ab561de50cfe41126e5bff404913c83fdc
+SHA512:
+  metadata.gz: ce1bc1a2cf8a88b731da104e24a33c77561aea36295346558e2e8240a563460ddf8eea98a9bc289933079805ca384224a08a22c9f0c19b2ca2b28fc01c40ae3f
+  data.tar.gz: 3dcb7344648d8b2aec5d48499cc0a2cc5a800eee73cea6940dda4bc6114caa49758c27313e9c54d0d8e7065d3dbbcdb9c0ad0e6d8ebfc2ae7eeac22dd832dfc6

data/README.md

@@ -0,0 +1,281 @@
+# Logalize
+
+Logalize is a Javascript wrapper for browser's developer console. Its goal is to make debugging
+easier.
+
+This is a Rails gem version of the library. For source files and an npm package, go [here](https://github.com/akxcv/logalize).
+
+## Installation
+
+Add this to your `Gemfile`:
+```
+gem 'logalize'
+```
+
+Add this to your `application.js`:
+```
+//= require logalize
+```
+
+Add this to your `application.css`:
+```
+*= require logalize
+```
+
+## 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?
+
+Logalize solves this problem by introducing a flexible enable/disable mechanism. First of all, you
+can enable or disable it during initialization: `logalize = new Logalize({ enabled: debug })`
+(assuming that `debug` is `true` in development and `false` in production). But also, you can
+enable or disable Logalize in your browser (`logalize.enable()` or `logalize.disable()`), which will
+override the global `enabled` option. Thus, you can easily switch Logalize 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)
+
+Logalize solves this by creating a different implementation of groups. With Logalize, you can use
+groups like this:
+
+```js
+logalize.group('my namespace').log('hello from my namespace')
+/* or */
+logalize.group('my namespace', function () {
+  logalize.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.
+
+Logalize 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
+logalize.profile('profile1')
+myVar = myFunction()
+logalize.profileEnd()
+
+/* is the same as */
+
+myVar = logalize.profile('profile1', myFunction)
+```
+
+- `group` is described in [grouping](#grouping).
+
+### Initialization options
+
+```js
+logalize = new Logalize({
+  enabled: true,
+  enableFormatting: true,
+  collapseGroups: false,
+  modifyConsole: true
+})
+```
+- `enabledByDefault`: Defines whether to enable or disable Logalize.
+When Logalize 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 Logalize needs to modify `console` upon initialization.
+Generally, modifying global objects is a bad thing to do, but this is required if you want Logalize to
+handle console output correctly. Logalize 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 Logalize work a little different from console's groups. There are two ways to group the output.
+
+```js
+/* method 1 */
+logalize.group('group one').log('inside group 1')
+
+/* method 2 */
+logalize.group('group one', function () {
+  logalize.log('inside group 1')
+})
+```
+
+You can easily mix methods together and nest groups however you want:
+
+```js
+logalize.group('user login', function () {
+  logalize.info('user login started')
+  logalize.group('credentials').log('credentials are [correct].green')
+  /* code */
+  logalize.info('[success].badge.green')
+})
+
+logalize.group('group 1').log('some more output')
+logalize.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
+
+Logalize 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
+
+Logalize 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 `logalize.error` and `logalize.trace` contain unneeded information**.
+Since `logalize.error` and `logalize.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/logalize](https://github.com/akxcv/logalize).*
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/akxcv/logalize.
+
+## 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/logalize/rails/engine.rb

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

data/lib/logalize/rails/version.rb

@@ -0,0 +1,5 @@
+module Logalize
+  module Rails
+    VERSION = '0.0.1'
+  end
+end

data/lib/logalize/rails.rb

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

data/lib/logalize.rb

@@ -0,0 +1,4 @@
+require 'logalize/rails'
+
+module Logalize
+end

data/vendor/assets/javascripts/logalize.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.Logalize=require("./index");
+},{"./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="logalize",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 Logalize(o){var e={enabled:!0,enableFormatting:!0,collapseGroups:!1,modifyConsole:!0};o||(o={});for(var r in e)o.hasOwnProperty(r)||(o[r]=e[r]);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 n=function(o,e){return GroupManager.clear(),BrowserAdapter[o].apply(BrowserAdapter,e)};console.log=function(){n("log",arguments)},console.debug=function(){n("debug",arguments)},console.info=function(){n("info",arguments)},console.warn=function(){n("warn",arguments)},console.error=function(){n("error",arguments)},console.assert=function(){n("assert",arguments)},console.clear=function(){GroupManager.clear()},console.count=function(){n("count",arguments)},console.dir=function(){n("dir",arguments)},console.dirxml=function(){n("dirxml",arguments)},console.group=function(){n("group",arguments)},console.groupCollapsed=function(){n("groupCollapsed",arguments)},console.groupEnd=function(){n("groupEnd",arguments)},console.profile=function(){n("profile",arguments)},console.profileEnd=function(){n("profileEnd",arguments)},console.time=function(){n("time",arguments)},console.timeEnd=function(){n("timeEnd",arguments)},console.timeStamp=function(){n("timeStamp",arguments)},console.trace=function(){n("trace",arguments)}}}var GroupManager=require("./groupManager"),BrowserAdapter=require("./browserAdapter"),Formatter=require("./formatter");Logalize.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),e=o.pop();if("function"==typeof e){this._isEnabled()&&BrowserAdapter.profile(o[0]);var r=e.call();return this.profileEnd(),r}this._isEnabled()&&BrowserAdapter.profile(o[0])},profileEnd:function(){this._isEnabled()&&BrowserAdapter.profileEnd()},time:function(){var o=[].slice.call(arguments),e=o.pop();if("function"==typeof e){this._isEnabled()&&BrowserAdapter.time(o[0]);var r=e.call();return this.timeEnd(o[0]),r}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),e=this.collapseGroups?"groupCollapsed":"group";if("function"==typeof o[o.length-1]){var r=o.pop();this._isEnabled()&&GroupManager.group(e,o,!0);var n=r.call();return this._isEnabled()&&GroupManager.ungroup(!0),n}return this._isEnabled()&&GroupManager.group(e,o),this},print:function(o,e){if(GroupManager.ungroup(),this._isEnabled()){var r=!document.hasFocus()&&GroupManager.previousStack.length+GroupManager.globalStack.length;if(r){var n=[],t=GroupManager.previousStack;t.unshift.apply(t,GroupManager.globalStack.reduce(function(o,e){return o.concat(e)},[])),GroupManager.previousStack=[];for(var i in t)n.push(t[i]);var a=n.join(" -> ")+" :: ";"string"==typeof e[0]?e[0]=a+e[0]:e.unshift(a)}this.formattableMethods.indexOf(o)>-1&&this.enableFormatting&&(e=Formatter.format(e)),r?(BrowserAdapter.groupCollapsed.apply(BrowserAdapter,e),BrowserAdapter.groupEnd()):BrowserAdapter[o].apply(BrowserAdapter,e)}},enable:function(){localStorage&&localStorage.setItem("logalizeEnabled","true")},disable:function(){localStorage&&localStorage.setItem("logalizeEnabled","false")},_isEnabled:function(){return localStorage&&localStorage.logalizeEnabled?"false"!==localStorage.logalizeEnabled:this.enabled}},module.exports=Logalize;
+},{"./browserAdapter":2,"./formatter":3,"./groupManager":4}]},{},[1]);

data/vendor/assets/stylesheets/logalize.css

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

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: logalize
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Alexander Komarov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-02-14 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  Logalize is a Javascript wrapper for browser's developer console.
+                            Its goal is to make debugging easier.
+email:
+- ak@akxcv.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/logalize.rb
+- lib/logalize/rails.rb
+- lib/logalize/rails/engine.rb
+- lib/logalize/rails/version.rb
+- vendor/assets/javascripts/logalize.js
+- vendor/assets/stylesheets/logalize.css
+homepage: https://github.com/akxcv/logalize
+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: []