tenshi Apr 28 2010 at 20:22

Hiqus — HIerarhical QUery String

10 min

2.8K

Это формат представления древовидных структур данных в виде одной строки в удобном для человека виде. Является обобщением формата «application/x-www-form-urlencoded» и как следствие — обратно совместим с ним. В основе Hiqus лежит всё тот же принцип представления данных в виде пар «ключ-значение» с той лишь разницей, что ключ может быть составным или пустым.

Данный формат уже используется такими монстрами как Яндекс (http://yandex.ru/yandsearch?date=within&text=hiqus&from_day=28&from_month=4&from_year=2009), Гугл (http://www.google.ru/search?as_q=hiqus&hl=ru&num=10&as_qdr=all) и многими другими, кому требуется передавать иерархические данные в строке запроса. Исключение составляют PHP-сайты, для которых традиционно используется свой, не слишком наглядный формат (пример, навскидку не нашёл, но выглядит он примерно так: ?user%5Bid%5D=123&user%5Bname%5D=Nick).

Описание

Hiqus-строка состоит из 1 и более кусочков, разделённых между собой разделителем, в роли которого может выступать знакомый нам из обычных query string амперсанд, из традиционных ЧПУ — слэш, из коммандной строки — пробел, из cookie string — точка-с-запятой, ну и до кучи — вертикальная чёрточка ;-)

Каждый «кусочек» состоит из собственно значения и идущим перед ним путём. Путь может быть пустым. После каждого элемента пути должен идти специальный разделитель, которым может быть знакомый нам из обычных query string знак равенства, из JSON — двоеточие, и удобный в использовании в HTML-формах — знак подчёркивания (ибо не кодируется при передаче).

Значение и элементы пути должны быть закодированы процентом в соответствии со спецификацией URI. Впрочем, парсеру должны быть важны лишь упомянутые специальные символы. Экранировать ли остальные — зависит от того, где и как будет использоваться hiqus-строка.

Элемент пути может быть пустой строкой, тогда вместо него будет использоваться автоматически генерируемое число. Например, «a==1» эквивалентно «a=0=1» при парсинге.

Если в пути всего 1 элемент, да и тот пустой, то положенный после него разделитель может опускаться. Например, "=blogs/=webstandards" эквивалентно «blogs/webstandards».

«Кусочки» добавляются в целевое дерево последовательно, что позволяет последующим затирать значения и даже поддеревья предыдущих. Например, «a=b=1/a=1» эквивалентно «a=1».

Примеры

Пусть у нас есть такой чпу: /blogs/webstandards/92300/
Если его распарсить как hiqus, то получится объект с таким JSON представлением: { '0': 'blogs', '1': 'webstandarts', '2': '92300' }

Пусть мы отправили форму и получили такую query string: q=hiqus&target_type=blogs&target_subtype=offtopic
Результат парсинга будет примерно такой: { q: 'hiqus', target: { type: 'blogs', subtype: 'offtopic' } }

Пусть мы вызвали наш скрипт из консоли передав ему такие параметры: list users sex=female limit=100
После парсинга получим: { '0': 'list', '1': 'users', 'sex': 'female', limit: '100' }

Пусть нам пришли такие печеньки: sid=1234;login=tenshi
Распарсим и получим: { sid: '1234', login: 'tenshi' }

Эталонная реализация на яваскрипте

var Hiqus= new function(){ Version: 1 Description: "parse, serialize and merge any 'HIerarhical QUery String'" License: 'public domain' Implementation: var sepHiqusList= '/|; &' var sepPathList= '=:_' var sepHiqusDefault= sepHiqusList.charAt(0) var sepPathDefault= sepPathList.charAt(0) var sepHiqusRegexp= RegExp( '[' + sepHiqusList + ']', 'g' ) var sepPathRegexp= RegExp( '[' + sepPathList + ']', 'g' ) var encode= function( str ){ return encodeURIComponent( str ).split( '_' ).join( '%5F' ) } var decode= function( str ){ return decodeURIComponent( str ) } var splitHiqus= function( str ){ return str.split( sepHiqusRegexp ) } var splitPath= function( str ){ var path= String( str ).split( sepPathRegexp ) for( var j= path.length - 1; j >= 0; --j ) path[ j ]= decode( path[ j ] ) return path } var get= function( ){ var obj= this for( var i= 0, len= arguments.length; i < len; ++i ){ var name= arguments[ i ] if( !name ) throw new Error( 'name is empty' ) obj= obj[ name ] if( typeof obj !== 'object' ) return obj } return obj } var placin= function( ){ var obj= this for( var i= 0, len= arguments.length; i < len; ++i ){ var name= arguments[ i ] if( name && Number( name ) != name ){ var o= obj[ name ] if(( !o )||( typeof o !== 'object' )) o= obj[ name ]= [] } else { var o= [] obj.push( o ) } obj= o } return obj } var put= function( ){ var obj= this var len= arguments.length if( !len ) return this var val= arguments[ len - 1 ] var key= arguments[ len - 2 ] if( len > 2 ){ var path= [] for( var i= len - 2; i-- ;) path[ i ]= arguments[ i ] obj= placin.apply( obj, path ) } if( typeof val === 'object' ){ var v= ( len === 1 ) ? obj : placin.call( obj, key ) for( var i in val ) if( val.hasOwnProperty( i ) ) put.call( v, i, val[ i ] ) } else { val= String( val ) if( !key || Number( key ) == key ) obj.push( val ) else obj[ key ]= val } return this } var parsin= function( str ){ var chunks= splitHiqus( str ) for( var i= 0, len= chunks.length; i < len; ++i ){ var path= chunks[i] if( !path ) continue path= splitPath( path ) put.apply( this, path ) } return this } var serialize= function( prefix, obj ){ if( !obj ) return '' if( typeof obj !== 'object' ){ if( prefix === sepPathDefault ) prefix= '' return prefix+= encode( obj ) } var list= [] for( var key in obj ) if( obj.hasOwnProperty( key ) ){ var k= ( Number( key ) == key ) ? '' : encode( key ) var chunk= serialize( prefix + k + sepPathDefault, obj[ key ] ) if( chunk ) list.push( chunk ) } return list.join( sepHiqusDefault ) } var Hiqus= function( ){ var hiqus= ( this instanceof Hiqus ) ? this: new Hiqus var data= placin.call( hiqus, '_data' ) for( var i= 0, len= arguments.length; i < len; ++i ){ var arg= arguments[i] if( arg instanceof Hiqus ) arg= arg._data var invoke= ( Object( arg ) instanceof String ) ? parsin : put invoke.call( data, arg ) } return hiqus } Hiqus.prototype= new function(){ this.put= function(){ var hiqus= Hiqus( this ) put.apply( hiqus._data, arguments ) return hiqus } this.get= function( ){ var val= get.apply( this._data, arguments ) if( typeof val === 'object' ) val= put.call( [], val ) return val } this.sub= function(){ var hiqus= Hiqus() var val= get.apply( this._data, arguments ) if( typeof val !== 'object' ) val= [ val ] hiqus._data= val return hiqus } this.toString = function(){ var str= serialize( '', this._data ) this.toString= function(){ return str } return str } } Export: return Hiqus Usage: alert( Hiqus ( Hiqus( '| a:b:c:1 / a:b: ; a:b::c & a=b__d' ) .sub( 'a', 'b' ) .put( [ 'e', 'f' ] ) , 'g/h' ) .get( 4 ) ) // alerts 'g' }

Hiqus-объекты реализауют паттерн Immutable, принимая необходимые данные через конструктор. У него может быть произвольное число параметров одного из следующих типов:

Строка. Будет произведён её парсинг и добавление в дерево.
Hiqus-объект. Его данные будут примёржены к дереву.
JSON. Аналогично Hiqus-объекту.

Методы hiqus-объекта:

put — возвращает новый объект, являющийся копией исходного, но с установленным значением по определённому пути. Hiqus().put( {user: { name: 'Nick' } } ) эквивалентно Hiqus().put( 'user', { name: 'Nick' } ) и эквивалентно Hiqus().put( 'user', 'name', 'Nick' )
get — возвращает копию значения по определённому пути. Hiqus().get( 'user', 'name' ) вернёт неопределённость, а Hiqus('Nick;John').get() вернёт ['Nick','John']
sub — создаёт новый объект на основе значения по определённому пути. Hiqus('users::Nick|users::John').sub('users') эквивалентно Hiqus('Nick;John')
toString — преобразует в строку, используя слэш и знак равенства в качестве разделителей. Результат сериализации кэшируется.

Тесты

;(function( x, y ){ if( '' + x == y ) return arguments.callee console.log( x, y ) throw new Error( 'fail test: [ ' + x + ' ]!=[ ' + y + ' ]' ) }) ( Hiqus( ), '' ) ( Hiqus( {} ), '' ) ( Hiqus( [] ), '' ) ( Hiqus( [1] ), '1' ) ( Hiqus( {'':1} ), '1' ) ( Hiqus( {'':{'':1}} ), '==1' ) ( Hiqus( [1,2] ), '1/2' ) ( Hiqus( {1:2} ), '2' ) ( Hiqus( {a:1} ), 'a=1' ) ( Hiqus( {'a_b':1} ), 'a%5Fb=1' ) ( Hiqus( {a:{b:1}} ), 'a=b=1' ) ( Hiqus( {a:1,b:2} ), 'a=1/b=2' ) ( Hiqus( {a:1},{b:2} ), 'a=1/b=2' ) ( Hiqus( {a:1},'b:2' ), 'a=1/b=2' ) ( Hiqus( {a:1},{b:2} ), new Hiqus( {a:1},{b:2} ) ) ( Hiqus( Hiqus({a:1}), Hiqus({b:2}) ), 'a=1/b=2' ) ( Hiqus( '' ), '' ) ( Hiqus( 'a' ), 'a' ) ( Hiqus( '=a' ), 'a' ) ( Hiqus( '==1' ), '==1' ) ( Hiqus( 'a=1' ), 'a=1' ) ( Hiqus( 'a:1' ), 'a=1' ) ( Hiqus( 'a_1' ), 'a=1' ) ( Hiqus( 'a=b=1' ), 'a=b=1' ) ( Hiqus( 'a=1/b=2' ), 'a=1/b=2' ) ( Hiqus( 'a=1;b=2' ), 'a=1/b=2' ) ( Hiqus( 'a=1 b=2' ), 'a=1/b=2' ) ( Hiqus( 'a=1&b=2' ), 'a=1/b=2' ) ( Hiqus( 'a=1|b=2' ), 'a=1/b=2' ) ( Hiqus( '1/2' ).get(), '1,2' ) ( Hiqus( 'a=1/b=2' ).get('a'), '1' ) ( Hiqus( 'a=1=2/b=2=3' ).get('b','0'), '3' ) ( ( ( a= Hiqus( 'a=1/b=2' ) ).get( 'a' ), a ), 'a=1/b=2' ) ( Hiqus( 'a=1/b=2' ).sub(), 'a=1/b=2' ) ( Hiqus( 'a=b=1/a=c=2/d=3' ).sub( 'a' ), 'b=1/c=2' ) ( Hiqus( 'a=b==1/a=b==2' ).sub( 'a', 'b' ), '1/2' ) ( ( a= Hiqus( 'a=1/b=2' ) ).sub( 'a' ) && a, 'a=1/b=2' ) ( Hiqus( 'a=1' ).put( {b:2} ), 'a=1/b=2' ) ( Hiqus( 'a=1' ).put( 'a', {b:2} ), 'a=b=2' ) ( ( a= Hiqus( 'a=1' ) ).put( 'b=2' ) && a, 'a=1' ) ;

Tags:

Hubs:

IT Standards