bit-protocol 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d3b4bed5a4a0d7557fc41fa9c9a99483284b1d98f4837de98530982fedbbbd71
+  data.tar.gz: 9dae1cf57c7cc9cfb90d0d79f80fdbf2196199b8e2087c61295cd1c410132acd
+SHA512:
+  metadata.gz: d6c8abc14a7ee4c3f61def944e08dbbf75a3930f41e7d78820a0a086a3504c46040b91079fddc7e9edbae4aafcbeed316fbb68cb968dc96cc9fe0b033e3bc1e6
+  data.tar.gz: e4b7f2570af27f2161329bb34b7d708a5c7b2d67e93bfd87112f2f8e0fc40a157ef8982539b20627dbfcdd00f5c400823f2173684729cc820c583295bc75597c

data/GEMFILE

@@ -0,0 +1,2 @@
+
+gem "bitproto", :git=>"https://github.com/ChenMeng1365/bitproto.git"

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 ChenMeng1365
+
+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.

data/README.md

@@ -0,0 +1,112 @@
+# bitproto
+
+主要用于位操作、位解构和二进制编码。
+
+## BitOp
+
+位操作模块，提供基本二进制比特位的操作。
+
+分组 & 截取：
+
+- `stack(num)`将整数按8位分组。
+- `hextack(num)`将整数按4位分组。
+- `seek(bitstream, hidx, tidx, full)`截取比特位串`bitstream`的子串(从`hidx`到`tidx`)，`full`设置为字符串省略长度，对超长字符串仅显示部分子串(不影响其值)。
+
+进制转换 & 值面转换：
+
+- `hex2bin(num)`对于(十六进制)大整数，按8位二进制分组转换为字符串并连接起来；对于十六进制字符串，按4位二进制分组转换为字符串并连接起来。
+- `bin2hex(num)`对于(二进制)大整数，按1位十六进制分组转换为字符串并连接起来；对于二进制字符串，按1位十六进制分组转换为字符串并连接起来。
+- `bitval(num)`将二进制字符串转换为整数。
+- `hexval(num)`将十六进制字符串转换为整数。
+
+## BitStream
+
+定义了比特位数据流字符串，以整数序列按字节存储。
+
+导入方式 & 值展示方式：
+
+- 表值的数字字符串(`:hex`,`:bin`,`:dec`)
+- 原始二进制数据(`:raw`)
+- 整数序列(`:seq`)
+
+## BitMark
+
+
+
+## BitProtocol
+
+定义了以比特位组织数据的协议，用于对比特位数据流进行解析和编码。
+
+※ 临时实现，建议重写 ※
+
+协议载入方法：
+
+- load(path): 读取指定协议(JSON)文件
+- parse(setting,reset_flag): 解析协议(JSON)文档
+- reset(): 重置协议生成树
+
+表达式解析方法：
+
+- eval(type, content): 根据类型估值
+- expr(condition): 条件表达式拆分，解析为变量、操作符、值序列
+- var(condition): 条件表达式解析，以`${}`或`$[]`提取变量中的名称
+- words(condition): 条件表达式解析，以`()`提取序列，以`,`分隔子元素
+- oprt(condition): 条件表达式解析，提取`==`、`in`、`exist`等操作符
+
+查询实现方法：
+
+- trace(tree,rtree,dom): 字段验证中**查询**的一种实现方法，通过遍历字段值树，构成一组带有实例值的反向查询路径
+- rtrace(tree,key,dom): 字段验证中**查询**的一种实现方法，根据反向查询路径构成一颗反向查询树
+
+估值验证方法：
+
+- validate(env): 根据环境变量验证协议生成树，根据验证的当前方式，需要做两次估值检查
+- evaluate(expr): 条件表达式估值，给协议生成树变量赋值
+- verify(verification, should, actual, &process): 根据验证原则和验证方式，判断协议预定值和数据流实际值是否符合
+- finale(criteria, result): 根据验证结果和验证准则设置，判断是否通过验证
+- normal?(report, rule): 输入规则决定协议匹配后是否达成某项协议的正常结果
+
+该模块维持两个存储：`@_bp_`(比特协议数据流)和`@_pt_`(协议生成树)。前者用以将比特位协议文档读取，加载为原生数据；后者负责构建协议树结构，并验证一些检查条件。
+
+比特位协议通过字段定义数据结构和所需维持的规范。
+
+一个转换为JSON格式的原始比特协议数据流字段如下：
+
+```json
+  "字段名称":  {
+    "description": "字段描述",
+    "start-bit": 0,     // 字段起始位索引
+    "finish-bit": 19,   // 字段结束位索引
+    "type": "HEX",      // 字段类型
+    "value": {          // 字段值
+      "字段值": "字段值描述"
+    },
+    "condition": "字段存在条件",    // 字段存在条件
+    "verification": "精确匹配",     // 字段验证方式
+    "criteria": "失败"              // 字段验证结果
+  },
+```
+
+* 字段名称、字段描述、字段值描述：均为字符串，用以帮助理解该字段含义。
+* 字段起始位索引、字段结束位索引：为非负正整数，指定比特位范围，计数从0开始。
+* 字段类型：字符串，指定字段值的值表示方式。这里的表示方式，是指对数据流解构后，按协议中本处指定的方式进行数据处理，得到的数据值。比如指名为`HEX`，表示获取该字段数据后，以十六进制字符串形式转换数据，再对其进行校验和运算。`HEX`、`BIN`、`DEC`均是字符串，`STR`为无限制字符串，`INT`和`FLT`为整数和浮点数，`PTR`为仅作提取不做展示加工的原始数据，一般用于运算。可以在类型后面标注长度以方便对齐，比如`BIN(4)`、`HEX(2)`等。
+* 字段值：散列对象，键值对表示字段值和其描述。字段值的设定需要和字段类型保持一致，一般一个具体的字段值是枚举值类型的实例，但为了提高匹配效率，也可以通过列表(`Array`)、范围(`Range`)、集合(`Set`)等方式为一类值做归集。还`PTR`类型是个例外，它的值是协议中另外一个字段名称。
+* 字段值验证方式：字符串，指定字段值的验证方式，根据值的指定方式支持逻辑运算、比较运算、集合运算、谓词运算和查询操作，具体谓词见<< Verification >>。其中除了查询是根据值反向查询描述来匹配其含义，其他验证方式均直接对值进行运算并校验。
+* 字段存在条件：字符串，有些场合字段并非必须出现，通过校验该字段是否存在的条件表达式，在估值不成立时不适用该字段。表达式中适用各类运算符甚至函数，使用`$[PTR]`来指向另一个字段并引用其值。
+* 字段值验证结果：字符串，指定字段验证结果的作用，当验证`失败`时，该字段不通过，数据流不匹配协议；当验证`忽略`时，即使字段验证失败，也不影响数据流适用其他的匹配。
+
+| Verification | Name | Description |
+| ------------ | ---- | ----------- |
+| AND          | 且   | 逻辑        |
+| OR           | 或   | 逻辑        |
+| NOT          | 非   | 逻辑        |
+| MATCH        | 匹配 | 精确        |
+| LESS         | 小于 | 精确        |
+| GREATER      | 大于 | 精确        |
+| IN           | 属于 | 范围        |
+| INCLUDE      | 包含 | 范围        |
+| EXIST        | 存在 | 限定        |
+| ALL          | 全部 | 限定        |
+| QUERY        | 查询 | 反向        |
+
+<< Verification >>

data/bitop.rb

@@ -0,0 +1,57 @@
+
+module BitOp
+  module_function
+
+  def stack num
+    sequence, left = [], num
+    until left==0
+      rest = left & 0b11111111
+      left = left >> 8
+      sequence.unshift rest
+    end
+    return sequence
+  end
+
+  def hextack num
+    sequence, left = [], num
+    until left==0
+      rest = left & 0b1111
+      left = left >> 4
+      sequence.unshift rest
+    end
+    return sequence
+  end
+
+  def hex2bin num
+    return self.stack(num).map{|c|"%08b"%c}.join              if num.is_a?(Integer)
+    return num.each_char.map{|c|"%04b" % (eval("0x#{c}"))}.join if num.is_a?(String)
+  end
+
+  def bitval num
+    eval("0b"+num)
+  end
+
+  def bin2hex num
+    return self.hextack(num).map{|c|"%0x"%c}.join                   if num.is_a?(Integer)
+    return num.split('').each_slice(4).map{|c|"%0x"%eval("0b#{c.join}")}.join if num.is_a?(String)
+  end
+
+  def hexval num
+    eval("0x"+num)
+  end
+
+  def seek bitstream, head_index=nil, tail_index=nil, full=false
+    q = bitstream.val(:seq, full).select{|c|c!='...'}.map{|c|"%08b"%c}.join
+    s = 0                     if head_index==:first        || head_index==nil
+    s = q.length + head_index if head_index.is_a?(Integer) && head_index < 0
+    s = head_index            if head_index.is_a?(Integer) && head_index >= 0
+    s = q.length - 1          if head_index.is_a?(Integer) && head_index >= q.length
+    e = -1                    if tail_index==:last
+    e = q.length + tail_index if tail_index.is_a?(Integer) && tail_index < 0
+    e = tail_index            if tail_index.is_a?(Integer) && tail_index >= 0
+    e = q.length - 1          if tail_index.is_a?(Integer) && tail_index >= q.length
+    e = s                     if tail_index==nil           || (e.is_a?(Integer) && s.is_a?(Integer) && e < s)
+    # p [q, s, e]
+    q[s..e]
+  end
+end

data/bitproto.rb

@@ -0,0 +1,174 @@
+require 'bitop'
+require 'bitstream'
+
+module BitProtocol
+  module_function
+
+  def load path
+    self.reset unless @_pt_
+    path = path[-5..-1]=='.json' ? path : path+'.json'
+    @_bp_ = JSON.parse File.read(path)
+    return @_bp_, @_pt_
+  end
+
+  def parse setting, reset=false
+    self.reset if !@_pt_ || reset
+    @_bp_ = JSON.parse setting
+    return @_bp_, @_pt_
+  end
+
+  def reset
+    @_pt_ = {}
+  end
+
+  def validate env={}
+    inst, checks,report = env[:instance], [], []
+    (puts "Instance of BitProtocol is nil.";return nil) unless inst
+    console_log = env[:log]
+
+    @_bp_.each do|key, set|
+      desc = set['description']
+      si, ei = set['start-bit'], set['finish-bit']
+      type = set['type']
+      should = set['value']
+      
+      bits = BitOp.seek(inst, si, ei)
+      actual = self.eval(type, bits)
+      
+      cond = set['condition'] ? self.expr(set['condition']) : []
+      vrfy = verify(set['verification'], should, actual)
+      cert = finale(set['criteria'], vrfy)
+
+      @_pt_["$[#{key}]"] = actual if self.evaluate(cond) && vrfy
+      checks << [key, desc, si, ei, type, should, actual, cond, vrfy, cert]
+    end
+
+    checkz = []
+    checks.each do|check|
+      key, desc, si, ei, type, should, actual, cond, vrfy, cert = check
+      if vrfy && self.evaluate(cond)
+        @_pt_["$[#{key}]"] = actual
+      end
+      checkz << [key, desc, si, ei, type, should, actual, cond, vrfy, cert]
+    end
+
+    checkz.each do|check|
+      key, desc, si, ei, type, should, actual, cond, vrfy, cert = check
+
+      if self.finale(cert, vrfy) && self.evaluate(cond)
+        puts "Field #{key} is #{desc}." if console_log
+        show = (vrfy && should[actual]) ? should[actual] : (vrfy && vrfy!=true) ? vrfy : ''
+        puts "From #{si} to #{ei} is #{actual}, check should be #{!vrfy ? false : true}. >>>> #{show}" if console_log
+        unless cond.empty?
+          evar = self.evaluate(cond)
+          puts "Condition Expression is #{cond}, evaluation is #{evar}." if console_log
+        end
+        puts Array.new(128){'='}.join if console_log if console_log
+
+        report << [key.gsub('$[','').gsub(']',''), desc, show, actual, "#{type}[#{si}-#{ei}]"]
+      end
+    end
+
+    return report, @_pt_
+  end
+
+  def eval type, content
+    return case type
+    when 'HEX'; BitOp.bin2hex(content).to_s.upcase
+    when 'BIN'; content
+    when 'BIN(4)'; Array.new(4-content.length){'0'}.join+content
+    # when 'DEC'; 
+    when 'STR'; content
+    else; nil
+    end
+  end
+
+  def expr condition
+    vars = self.var(condition)
+    opts = self.oprt(condition)
+    words = self.words(condition)
+    vars = words.include?(vars) ? vars : vars
+    vals = words.include?(opts) ? words[(words.index(opts)+1)..-1] : words
+    return [vars, opts, vals]
+  end
+
+  def var condition
+    field = condition.to_s.match(/\$(\[|\{){1}(\w[\d|\_|\w]+)+(\]|\}){1}/).to_s
+    name = field.empty? ? nil : field.split('{').last.split('}').first
+    return name
+  end
+
+  def words condition
+    value = condition.to_s.match(/(\(){0,1}.*[\,|.]+.*(\)){0,1}/).to_s
+    list = (value.empty? ? condition.split(' ') : value.split('(').last.split(')').first.to_s.split(',')).map{|s|s.strip}
+    return list
+  end
+
+  def oprt condition
+    return '=='    if condition.to_s.include? '=='
+    return 'in'    if condition.to_s.include? 'in'
+    return 'exist' if condition.to_s.include? 'exist'
+    return nil
+  end
+
+  def evaluate expr
+    vars, opts, vals = expr # vars include $[] here
+    # p [vars, @_pt_[vars], opts, vals]
+    return case opts
+    when '=='; @_pt_[vars] == vals.first
+    when 'in'; vals.include?(@_pt_[vars])
+    when 'exist'; !!@_pt_[vars]
+    else; true
+    end
+  end
+
+  def verify verification, should, actual, &process
+    return case verification
+    when '精确匹配'
+      should.keys.include? actual
+    when '精确查询'
+      locate = self.rtrace(should, actual, '')
+      locate ? locate.gsub('/',' ').strip : false
+    else
+      false
+    end
+  end
+
+  def finale criteria, result
+    return case criteria
+    when '失败'; result
+    when '忽略'; !result
+    else; result; end
+  end
+
+  def trace tree,rtree,dom=''
+    tree.each do|name, node|
+      if node.is_a?(Hash)
+        rtree = self.trace(node, rtree, "#{dom}/#{name}")
+      elsif node.is_a?(Array)
+        node.each do|value| # must be an atom
+          rtree["#{dom}/#{name}"] = value
+        end
+      else
+        rtree["#{dom}/#{name}"] = node
+      end
+    end
+    return rtree
+  end
+
+  def rtrace tree, key, dom=''
+    rsort = self.trace(tree, {}, dom)
+    rtree = {}
+    rsort.each do|path, val|
+      rtree[val]=path
+    end
+    return rtree[key]
+  end
+
+  def normal? report, rule
+    return true if \
+      report.map{|r|r[0]}==['PB','AT','PI1','QoS'] && rule=='一般专线地址' ||
+      report.map{|r|r[0]}==['PB','AT','PI2','CC'] && rule=='网吧专线地址'
+    return false
+  end
+end

data/bitstream.rb

@@ -0,0 +1,29 @@
+
+class BitStream
+  def initialize option={}
+    option.each do|type, value|
+      case type.to_s.downcase.to_sym
+      when :hex; @stream = BitOp.stack( eval("0x#{value}") )
+      when :bin; @stream = BitOp.stack( eval("0b#{value}") )
+      when :dec; @stream = BitOp.stack( value.to_i )
+      when :raw; @stream = value[0].is_a?(String)  ? value.each_byte.map{|c|c.ord} : value
+      when :seq; @stream = value[0].is_a?(Integer) ? value : value.each_char.map{|c|c.ord}
+      else; @stream = []    
+      end
+    end
+  end
+
+  def val format='hex', full=false # := number of bytes
+    return []  if full.is_a?(Integer) && full <= 0
+    e = full+1 if full.is_a?(Integer) && full > 0
+    e = 1024   if full==false
+    t = @stream.length >= e ? '...' : nil
+    return case format.to_s.downcase.to_sym
+    when :hex; @stream[0..e].map{|c|"%02x"%c} + (t ? [t] : [])
+    when :bin; @stream[0..e].map{|c|"%08b"%c} + (t ? [t] : [])
+    when :dec; eval("0b"+@stream[0..e].map{|c|"%08b"%c}.join).to_s + (t ? t : '')
+    when :raw; @stream[0..e].map{|c|c.chr}.join + (t ? ' '+t : '')
+    when :seq; @stream[0..e] + (t ? [t] : [])
+    end
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: bit-protocol
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Matt
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+- !ruby/object:Gem::Dependency
+  name: casetdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+description: bit operating, destructuring, and encoding
+email:
+- matthrewchains@gmail.com
+- 18995691365@189.cn
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- GEMFILE
+- LICENSE
+- README.md
+- bitop.rb
+- bitproto.rb
+- bitstream.rb
+homepage: https://github.com/ChenMeng1365/network
+licenses:
+- AGPL-3.0
+metadata: {}
+rdoc_options: []
+require_paths:
+- "."
+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: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: bitproto
+test_files: []